Backend API
Use webhooks to get notified about events that happen in your Swell account. Swell is an event-based architecture that allows you to configure webhooks on a variety of events that occur within each data model. A webhook can be configured by a Swell App, or manually from the Swell dashboard, to receive incoming HTTP calls that contain data describing the event.
To configure a webhook manually, visit your Swell dashboard and go to Developer > Webhooks. Specify the URL to your webhook handler and one or more events to receive.
To view webhooks that have fired within your store, see the /events:webhooks endpoint.
See the Apps webhook reference to learn how to configure webhooks in Swell Apps.
Fields
id
objectIdautoThe unique identifier for the webhook.
alias
stringAlias used to refer to the webhook configuration.
url
stringrequiredURL endpoint for the webhook.
events
array of stringrequiredArray of trigger events for the webhook.
enabled
booleanDetermines whether the webhook is enabled. Defaults to false.
auto_disabled
booleanautoIndicates whether the webhook was automatically disabled. This occurs seven days after the first failed attempt and no subsequent successes.
retry_disabled_events
booleanDetermines whether the webhook retries disabled events.
attempts_failed
intDisplays the number failed webhook attempts.
date_first_failed
dateautoThe date the webhook's first failed attempt.
date_last_warned
dateautoThe date of the last warning for a failed attempt.
date_final_attempt
dateThe final attempt for a webhook after continuous failed attempts. Webhooks are disabled 7 days after the first failed attempt.
schedule
objectSchedule for specifying when a webhook is to be fired.
schedule.hour
intThe hour for which to fire the webhook. Min 0, max 23.
schedule.month_day
intThe day of the month for which to fire the webhook. Min 1, max 31.
schedule.month
intThe month for which to fire the webhook. Min 1, max 12.
schedule.week_day
intThe month for which to fire the webhook. Min 0, max 6.
date_scheduled
dateDate for which the webhook is scheduled to fire.
The webhook model
{
"url": "http://localhost:5000",
"enabled": false,
"alias": "webhook",
"description": null,
"events": [
"order.created",
"order.submitted",
"order.updated"
],
"api": "com",
"date_final_attempt": null,
"date_scheduled": null,
"date_created": "2021-09-27T16:30:11.837Z",
"date_updated": "2021-10-28T16:04:21.648Z",
"id": "6151f193ae97e82ccbf6f0a7"
}You may use an HTTPS URL for your webhook endpoint. In that case, Swell will validate your SSL certificate before sending event data. Your server must be correctly configured to support HTTPS.
Webhook event data is sent as JSON in a POST body. The payload represents a single event with attributes based on the event type. Events may contain additional data attributes that are useful in processing the event.
Your webhook might need to fetch the associated record using data.id before performing a relevant action.
If you need to verify that a webhook was sent from Swell's servers, you can check that it originates from one of the following IP addresses:
- 52.52.111.237
- 54.219.85.17
- 54.241.235.166
Response
{
"id": "58991ed385c95b9e2e0aa433",
"date_created": "2019-02-07T01:11:47.219Z",
"model": "subscriptions",
"type": "subscription.paid",
"data": {
"id": "58991ed285c95b9e2e0aa42c",
"payment_id": "5ca3806f0e41a74b7138d085"
}
}Your endpoint must respond to successful requests with a 2xx HTTP status code. All other information returned by your script will be ignored. Response codes outside this range will indicate that you were not able to receive the webhook event.
If a webhook is not acknowledged successfully, Swell will continue trying to send it once every hour for up to two days. After this time, we'll send an email alert and continue attempting to deliver the webhook every hour. If your endpoint does not respond after three days, you will be notified finally and the webhook will be disabled until further action is taken.
Unless otherwise specified, webhook requests have a timeout of 10 seconds. In cases where webhook handlers are long-running or resource-intensive, we recommend implementing a messaging queue to handle incoming webhook requests asynchronously.