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. The store's admins receive a warning email after every 10 failed attempts, at most once a day. If a webhook keeps failing for 4 days without a successful delivery, it is automatically disabled and the store's admins are notified. Developers can re-enable a disabled webhook, prompting the system to retry all pending webhooks. Pushing the app again with swell app push also re-enables it. Webhook requests have a 10-second timeout, and the endpoint must respond with a 2xx status code.

To stop retries for an event, respond with status 410, or with a non-2xx response whose JSON body includes "retry": false.

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"
  ],
  "enabled": true
}

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.