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.

A webhook can send a request on a schedule instead of in response to model events. To schedule a webhook, set events to ["webhook.scheduled"] and add a schedule object. Swell sends the request at minute 0 of each hour that matches the schedule, in UTC.

PropertyDescription
hourHour of the day, from 0 to 23.
month_dayDay of the month, from 1 to 31.
monthMonth of the year, from 1 to 12.
week_dayDay of the week, from 0 (Sunday) to 6 (Saturday).

An omitted property matches any value. A schedule without hour sends a request every hour of the matching days, and an empty schedule sends one every hour. When both month_day and week_day are set, the webhook fires on days that match either one.

A scheduled webhook first fires at the next matching time after it's installed. Failed requests are retried like other webhook requests.

The request body is the webhook.scheduled event. Its data contains the webhook's id, its schedule, and date_scheduled, the time the request was scheduled for:

{
  "id": "6911f0c0a1b2c3d4e5f60718",
  "type": "webhook.scheduled",
  "model": "webhooks",
  "data": {
    "id": "690e1a2b3c4d5e6f70819203",
    "schedule": { "week_day": 1, "hour": 9 },
    "date_scheduled": "2026-11-16T09:00:00.000Z"
  },
  "date_created": "2026-11-16T09:00:00.412Z"
}

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

PropertyDescription
descriptionA brief description of the webhook's purpose.
urlYour application's webhook endpoint URL.
eventsArray of event types to trigger this webhook, for example ['product.created', ...].
enabledIndicates whether the webhook is enabled. A webhook only sends events while it is enabled. Defaults to true when the webhook is first installed. Pushing the app again changes it only if the file sets it.
retry_disabled_eventsIndicates whether events that arrived while the webhook was automatically disabled are sent when it is enabled again. Defaults to true. Set it to false to discard them.
scheduleTimes to send a scheduled webhook, as an object with hour, month_day, month and week_day, in UTC. Requires events to be ["webhook.scheduled"]. See Scheduled 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:

webhooks/payments.json
{
  "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.

In addition to event data, your webhook will also receive properties indicating which store and environment triggered the event.

Here's an example of a scheduled webhook that sends a request every Monday at 9:00 UTC:

{
  "description": "Send a weekly report every Monday at 9:00 UTC",
  "url": "https://example.com/weekly-report",
  "events": ["webhook.scheduled"],
  "schedule": { "week_day": 1, "hour": 9 }
}