Webhooks

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.

The webhook model

Fields

id

objectIdauto

The unique identifier for the webhook.

alias

string

Alias used to refer to the webhook configuration.

api

stringrequired

API the webhook subscribes to—com for the store API.

url

stringrequired

URL endpoint for the webhook.

events

array of stringrequired

Array of trigger events for the webhook.

enabled

boolean

Determines whether the webhook is enabled. Defaults to false.

auto_disabled

booleanauto

Indicates whether the webhook was automatically disabled. This occurs seven days after the first failed attempt and no subsequent successes.

retry_disabled_events

boolean

Determines whether the webhook retries disabled events.

attempts_failed

int

Displays the number failed webhook attempts.

date_first_failed

dateauto

The date the webhook's first failed attempt.

date_last_success

date

Date of the last successful webhook delivery.

date_last_warned

dateauto

The date of the last warning for a failed attempt.

date_final_attempt

date

The final attempt for a webhook after continuous failed attempts. Webhooks are disabled 7 days after the first failed attempt.

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"
}

Create a webhook

When setting up webhooks for custom models, you will need to create them via the API referencing the events listed on the custom model. For webhooks that utilize Swell's standard models, we recommend configuration through the Swell dashboard under Developer tools > Webhooks—each standard model's events are easily referenced within the UI.

Arguments

url

stringrequired

URL endpoint for the webhook.

events

array of stringrequired

Array of trigger events for the webhook.

POST/:webhooks

const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');

await swell.post('/:webhooks', {
  url: 'http://localhost:5000',
  events: [
    'order.created',
    'order.submitted'
  ]
});

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"
}

Retrieve a webhook

Retrieve an existing webhook using the id that was returned during creation.

Arguments

id

objectIdauto

The unique identifier for the webhook.

GET/:webhooks/:id

const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');

await swell.get('/:webhooks/{id}', {
  id: '662ba123becf7601325cefa3'
});

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"
}

Update a webhook

Update a webhook.

Arguments

id

objectIdrequired

The unique identifier for the webhook.

Update

const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');

await swell.put('/:webhooks/{id}', {
  id: '6151f193ae97e82ccbf6f0a7',
  enabled: true
});

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"
}

List all webhooks

Return a list of webhooks.

Arguments

expand

string

Expand link fields and child collections by using the expand argument.

For example, expand=account would return a related customer account if one exists.

When the field represents a collection, you can specify the query limit.

For example, expand=variants:10 would return up to 10 records of the variants collection.

See expanding for more details.

fields

string

Returns only the specified fields in the result.

For example fields=name,slug would return only the fields name and slug in the response.

Supports nested object and array fields using dot-notation.

For example, items.product_id. The product id is always returned.

include

object

Include one or more arbitrary queries in the response which are potentially related to the main query.

See including for more details.

limit

int

Limit the number of records returned, ranging between 1 and 1000. Defaults to 15.

page

int

The page number of results to return given the specified or default limit.

search

string

A text search is performed using the search argument. Searchable fields are defined by the model.

For example, search=red would return records containing the word "red" anywhere in the defined text fields.

See searching for more details.

sort

string

Expression to sort results by using a format similar to a SQL sort statement.

For example, sort=name asc would return records sorted by name ascending.

See sorting for more details.

where

object

An object with criteria to filter the result.

For example, active=true would return records containing a field active with the value true.

It's also possible to use query operators, for example, $eq, $ne, $gt, and more.

See querying for more details.

GET/:webhooks

const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');

await swell.get('/:webhooks', {
  where: { enabled: true },
  limit: 25,
  page: 1,
});

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"
}

Delete a webhook

Delete a webhook.

Arguments

id

objectIdrequired

The id of the webhook to delete.

DELETE/:webhooks/:id

const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');

await swell.delete('/:webhooks/{id}', {
  id: '662ba123becf7601325cefa3',
});

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"
}

Using HTTPS

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.

Receiving webhooks

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

In addition, you should allow traffic from the following IP ranges (CIDR notation):

216.218.185.0/27
216.218.244.192/27
74.80.234.0/24

Response

{
  "id": "58991ed385c95b9e2e0aa433",
  "date_created": "2019-02-07T01:11:47.219Z",
  "model": "subscriptions",
  "type": "subscription.paid",
  "data": {
    "id": "58991ed285c95b9e2e0aa42c",
    "payment_id": "5ca3806f0e41a74b7138d085"
  }
}

Responding to webhooks

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.

← Back: Events Next: Files →

Fields

id

alias

api

url

events

enabled

auto_disabled

retry_disabled_events

attempts_failed

date_first_failed

date_last_success

date_last_warned

date_final_attempt

The webhook model

Arguments

url

events

id

alias

api

enabled

auto_disabled

retry_disabled_events

attempts_failed

date_first_failed

date_last_success

date_last_warned

date_final_attempt

The webhook model

Arguments

id

alias

api

url

events

enabled

auto_disabled

retry_disabled_events

attempts_failed

date_first_failed

date_last_success

date_last_warned

date_final_attempt

The webhook model

Arguments

id

alias

url

events

enabled

retry_disabled_events

schedule

schedule.hour

schedule.month_day

schedule.month

schedule.week_day

date_scheduled

The webhook model

Arguments

expand

fields

include

limit

page

search

sort

where

The webhook model

Arguments

id

The webhook model

Response