Webhooks

Webhooks enable real-time communication between the Swell platform and external services, by subscribing to any number of model events. The payload structure is based on the related Event record, containing fields such as event type, event payload, and more. Webhooks are processed asynchronously and feature a highly reliable retry system.

You can create a new webhook by adding a configuration to the app's webhooks/ folder, following the reference below.

While app functions are designed for logic hosted by Swell, app webhooks are intended to send events to external systems. You should decide which approach is best depending on how you prefer to manage and scale your application.

Webhook retries follow an incremental backoff strategy, with retries initially attempted within 1 minute and an exponential back-off thereafter. After 10 failed attempts, the next retry will be delayed by 12 hours, following the same strategy. Developers receive a warning email after 50 failed attempts. If a webhook fails for 7 days, it is automatically disabled. Developers can re-enable a disabled webhook, prompting the system to retry all pending webhooks. Webhook requests have a 30-second timeout before the endpoint must respond with an HTTP 200 status code.

For external webhooks, API secrets are the recommended method for webhook authentication. Developers can include them directly in the webhook URL, and validate the secret when a request is received from Swell.

The following table outlines the properties Swell supports when configuring app webhooks.

Use webhook configurations to streamline sending event updates to external systems. This is useful in cases where some or all of your app’s functionality is implemented in an external system.

Here’s an example of a basic webhook configuration:

{
  "description": "Send payment updates to Acme's aggregation pipeline"
  "url": "<https://example.com/handle-payments>",
  "events": [
    "payment.succeeded",
    "payment.failed"
  ]
}

In this example, Swell will send an asynchronous webhook request to the specified URL whenever one of the configured events is triggered in a store. See our backend API documentation to learn more about webhooks.