Webhooks

Webhooks are deliveries of data in response to events which happen within our Platform. They enable you, as external developers, to obtain information about changes and to potentially take actions as a result of that.

We currently support webhooks delivered over HTTPS connections, but please contact us for Google Cloud Pub/Sub or AWS EventBridge connections to our webhooks and we can add you to our private betas.

Validation

Please see the section on validating webhooks to learn how to audit webhooks received for authenticity. Please reject all webhooks that fail signature validation as they will not have been sent by us.

Delivery

We guarantee at-least-once semantics for all webhooks, with no guarantees on sequencing. This means that you might receive an order_create webhook before a customer_create webhook, or an order_update webhook before the corresponding order_create one.

There are two choices in how to handle this:

  1. Reject the unexpected delivery with a 4xx status code such as 409 CONFLICT
  2. Treat the unexpected delivery with an implict create action and upsert the presented resource

In the former case, our retry logic will redeliver the request shortly, hopefully having allowed the in-flight but not yet delivered “missing” webhook to have arrived.

To combat multiple deliveries, we provide a request_id as part of the webhook, which can be used to track and ignore additional deliveries. Whilst we do not expect to deliver a webhook more than once, we cannot guarantee it.

Retries

Failed webhooks will be retried using an exponential backoff up to a maximum of 20 attempts, covering a 12 day window from the first attempt to the last. The initial retry gap is 15 seconds, increasing thereafter.

Any non-2xx response code will be treated as a failure and thus retried.

General Format

All webhooks received will have the following container format. The data being transmitted will be held within the payload key, and other supporting information is contained within other top-level keys.

Attribute Type Description
action String The subject or kind of webhook being received.
payload varies The format of the webhook being received - please browse the types to explore
platform_id String The identifier of the platform this webhook originated from
request_id String A idempotence key to help you process requests. We only guarantee at-least-once semantics, so it is worth checking to see if you've seen the request before.
store_id String The identifier of the store this webhook originated from
topic String The group of webhooks this particular action is within, this can be used to help routing within the receiver or ignored.
version Integer The API version of the payload contained within this webhook

Table of contents