Swell is an event-based architecture that allows you to configure webhooks on a variety of events that occur within each of our base data models. These events are easily referenced when creating webhooks from within the Swell dashboard under 

. All configured webhooks are also available at 

The webhook object

Response

Webhook

alias

events

enabled

auto_disabled

retry_disabled_events

attempts_failed

date_first_failed

date_last_warned

date_final_attempt

schedule

date_scheduled

Swell is an event-based architecture that allows you to configure webhooks on a variety of events that occur within each of our base data models.

The webhook model

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 

—each standard model's events are easily referenced within the UI.

Create a webhook

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

Method reference for retrieving an existing webhook using the id that was returned during creation.

Retrieve a webhook

Update

Update a webhook

expand

fields

include

limit

page

search

sort

where

List all webhooks

Delete a webhook

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.

Using HTTPS for webhooks within the Swell Backend API. 

Using 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 

Example webhook payload

Receive webhooks with the Swell Backend API.

Receiving webhooks

Your endpoint must respond to successful requests with a 

 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.

Responding to webhooks with the Swell Backend API. 

Responding to webhooks

Use webhooks to get notified about events that happen in your Swell account. Configuring a webhook involves setting up your own application to receive incoming HTTP calls that contain data describing the event.

Settings > Webhooks. Specify the URL to your webhook handler and one or more events to receive.

Using webhooks within the Swell Backend API. 

Webhooks

Introduction

Authentication

Swell-node

Swell-php

Swell-py

Backend libraries

Validation errors

Handling errors

Errors

Query parameters

Filtering

Sorting

Limiting

Pagination

Searching

Expanding

Including

Querying

Aggregation

Set locale values

Retrieve localized content

Retrieve locale values

Localization

Formula

Pages

The product model

Create a product

Retrieve a product

Update a product

List all products

Delete a product

Products

The variant model

Create a variant

Retrieve a variant

Update a variant

List all variants

Delete a variant

Variants

The stock model

Create stock adjustments

Retrieve stock adjustment

List all stock adjustments

Stock

The category model

Create a category

Retrieve a category

Update a category

List all categories

Delete a category

The attribute model

Create an attribute

Retrieve an attribute

Update an attribute

List all attributes

Delete an attribute

Attributes

The purchase links model

Create a purchase link

Retrieve a purchase link

Update a purchase link

List all purchase links

Delete a purchase link

Purchase links

The cart model

Create a cart

Retrieve a cart

Update a cart

Convert carts to orders

List all carts

Delete a cart

Carts

The order model

Create an order

Retrieve an order

Update an order

List all orders

Delete an order

Orders

The payment model

Create a payment

Retrieve a payment

Refund a payment

List all payments

Payments

The refund model

Issue a refund

Retrieve a refund

List all refunds

Refunds

The shipment model

Create a shipment

Update a shipment

Retrieve a shipment

List all shipments

Shipments

The return model

Create a return

Retrieve a return

Update a return

List all returns

Returns

The subscription model

Create a subscription

Retrieve a subscription

Update a subscription

List all subscriptions

Delete a subscription

Subscriptions

Create a digital subscription plan

Create a plan with physical items

Subscription plans

The account model

Create an account

Retrieve an account

Update an account

List all accounts

Delete an account

Accounts

The account address model

Create an account address

Retrieve an account address

Update an account address

List all account addresses

Delete an account address

Account addresses

The account cards model

Create an account card

Retrieve an account card

Update an account card

List all account cards

Delete an account card

Account cards

The account credit model

Create an account credit

Retrieve an account credit

Update an account credit

List all account credits

Delete an account credit

Account credits

The invoice model

Retrieve an invoice

List all invoices

Invoices

The coupon model

Create a coupon

Coupons

Backend API

Filter

Results

Webhooks