Developer Center: 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.

Creating a webhook

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.

Creating a webhook through Backend API

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

Custom models and webhooks

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.

👉

When setting up webhooks for custom models, you will need to create them via the API. Webhook configuration available under the Settings > Webhooks interface does not include events from custom models.

Creating a webhook for a custom model

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.

Creating the webhook

POST/:webhooks

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

Posting to the custom model

POST/wishlist

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

Inspecting the ngrok web interface

It would look something like this:

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

Real-time order webhooks

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.

💡

Event-based webhooks will fire asynchronously, but real-time order webhooks will fire during the request. That means real-time order webhooks will run before their event-based counterparts.

Custom Tax Calculation

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.

Use a real-time order webhook to calculate custom tax

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

Custom Shipping Calculation

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.

PUT/carts/{id}

$ 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.

PUT/carts/{id}

$ 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 \