Webhook basics

Webhooks extend the functionality of your store. Swell’s event-based architecture lets you configure webhooks for any events that occur within each of our base data models. These events are easily referenced when creating webhooks from within the Swell dashboard under Developer > Webhooks.

A webhook is a callback to a third party, triggered by an event such as when an account is created or a checkout cart is abandoned. When triggered, the webhook makes an HTTP request to a URL that you’ve chosen. After the incoming POST request is validated, the webhook prompts a behavior such as a user being sent an email that they’ve successfully created an account or that their cart was abandoned.

To configure a webhook, navigate to Developer > Webhooks in the dashboard and click the Add webhook button. You will then need to enter the URL of the webhook, an alias, and the events used to trigger the webhook. Click the Save button on the popup window and settings page when you are finished.

await swell.post('/:webhooks', {
  alias: "Webhook Test",
  url: "https://example.com",
  events: [
   "product.created",
   "product.updated"
  ]
)};

Swell also supports the use of webhooks with custom models. Upon creation, each custom model is embedded with three basic events: created, updated, and deleted—meaning each of these events can be used to trigger a webhook when working with custom models.

As mentioned previously, when you want to create webhooks relating to custom models, you’ll have to create the webhook via API rather than within the dashboard flow. Additionally, we recommend setting up and running a tunneling service such as ngrok to test and configure these webhooks.

Once you have a tunneling service, you can create a custom model through the Model Editor. Navigate to Developers > Models > New Model or through the Backend API. For this example, we’ll create a wishlist model.

await swell.post('/:webhooks', {
  alias: "Wishlists",
  url: "https://example.ngrok.io",
  events: [
    "wishlist.created",
    "wishlist.deleted"
  ]
)};

await swell.post('/wishlist', {
  // Add fields as configured
)};

{
    "model": "wishlist",
    "type": "wishlist.created",
    "data": {
        "customer_id": "609bd48f11d6bf437c7b0a42",
        "products": [
            {
                "product_id": "5e19fefef0295d688e8fa34d",
                "id": "623b1d64b1869d013d37e960"
            },
            {
                "product_id": "5e19fefef0295d688e8fa34d",
                "id": "623b1d64b1869d013d37e961"
            }
        ],
        "date_created": "2022-03-23T13:15:16.729Z",
        "id": "623b1d64b1869d013d37e95d"
    },
    "date_created": "2022-03-23T13:15:17.017Z",
    "date_updated": "2022-03-23T13:15:17.084Z",
    "webhooks_pending": 1,
    "id": "623b1d65b1869d013d37ebed"
}

With real-time order webhooks, you can receive incoming HTTP calls as soon as an event triggers, such as a customer creating an order. When this happens, you can return a JSON response file and update information about the order. You can use real-time order webhooks with Swell’s hosted checkout and custom checkout in order to update shipping and tax information in real-time.

For example, let’s say that your store uses a custom tax service for calculating tax. When a customer checks out, a real-time order webhook will make a call to the custom tax service and return the tax information to the customer in real time. Other examples of real-time order webhooks include providing up-to-date shipping rates/quotes, custom shipping calculations, and protection against fraudulent transactions.

A real-time order webhook for a custom tax calculation service will fire when billing data is edited on the cart. If you are using a real-time order webhook to communicate with the custom tax service, you can provide the custom tax amount within an item's taxes array in the response body.

$respond({
  status: 200,
  body: {
    items: [{
      id: itemId,
      taxes: [
      { amount: customAmount }
      ]
    }]
  }
})

Use a real-time order webhook to show dynamic shipping prices from a custom shipping service. When shipping data is edited on the cart, this real-time order webhook will fire, overriding the standard shipment rate based on data passed within the webhook.

$ curl https://api.swell.store/carts/{id} \
-d shipment_rating[0][services][0][id]=standard \
-d shipment_rating[0][services][1][price]=25 \

Setting up a custom shipping service on-the-fly is another scenario for using a real-time order webhook.

$ curl https://api.swell.store/carts/{id} \
-d shipment_rating[0][services][0][id]=standard \
-d shipment_rating[0][services][1][name]=Custom Shipping Service \
-d shipment_rating[0][services][2][price]=100 \