App functions and webhooks extend the functionality of your store. Swell’s event-based architecture lets you configure hooks for any events that occur within each data model.

An app function is contained by an app and configured to receive any standard or custom event, performing actions with the API or returning data to a real-time event.

A webhook is a callback to a third party. When triggered, the webhook makes an HTTP request to a URL that you’ve chosen.

Apps can contain both functions and webhooks configurations, while webhooks can also be configured directly in the Swell dashboard.

Creating an app function

App functions are hosted by Swell on top of the Cloudflare Worker network, and deployed using the Swell CLI. When deployed, functions are automatically configured and triggered by system events. They can also be called directly by external apps.

Creating a webhook

Webhooks can be configured by apps, or configured manually. To configure a webhook manually, navigate to Developer → Webhooks in the dashboard and click the Add webhook button. You will then enter the URL of the webhook, an alias, and the events used to trigger the webhook.

Custom models and events

Swell also supports the use of functions and 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 function or webhook when working with custom models.

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

Order webhook response to calculate custom tax
{
  items: [{
    id: [item_id],
    taxes: [
      { amount: [custom_amount] }
    ]
  }]
}

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 \