Receive Events

Subscribe to Sibi events via webhooks.

Receiving Events via Webhook

Endpoint URL — the https endpoint SIBI will POST deliveries to.
Topics — a comma separated list of the topics you want, for example order.created, order.updated. Leave it empty to receive every topic.
Test webhook — a test webhook receives only events from the test environment, and a live webhook only live events. This cannot be changed after the webhook is registered.

Webhook limit

An organization can have 5 webhooks at a time, test and live combined. If you need more, email us.

Disabling a webhook

A webhook’s Status on the Webhooks page controls whether it receives events. A Disabled webhook is skipped when an event fires.

Redrive is also unavailable on a disabled webhook, so deliveries recorded before it was disabled cannot be re-sent until it is enabled again.

Deleting a webhook

Open a webhook from the Webhooks page and select Delete.

Authentication

Once your server is configured to receive payloads, it’ll listen for any payload sent to the endpoint you configured. For security reasons, you’ll want to limit requests to those coming from Sibi.

SIBI signs every delivery with the webhook’s signing secret: we calculate an HMAC-SHA256 of the raw request body using the secret and set the base64 encoded result in the HTTP-X-SIBI-SIGNATURE-256 http header. Compare that header against your own computation to confirm the request came from SIBI. For an example see below.

Verify payload signature

const webhookSignature = req.get('HTTP-X-SIBI-SIGNATURE-256');
const hash = crypto.createHmac('sha256', secret).update(req.rawBody, 'utf8').digest('base64');
const isValid = hash === webhookSignature;

Ensuring You Receive Events

If a webhook request fails, we will retry 5 times with a backoff before permanently failing.

Status Code Retry Policy

We’ll consider a webhook delivery successful only if your server returns a status code in the range 200-299. If your server returns any status code outside this range (such as 3xx, 4xx, or 5xx), we will treat it as a failure and retry the delivery.

Monitoring Deliveries

The SIBI Developer Portal records every delivery we send you: the payload, the outcome, and the status code and response body of each attempt. You can search deliveries by the identifiers inside their payloads, and re-send one after fixing your endpoint. Delivery records are kept for 90 days. See Monitor Webhook Deliveries.

Filtering Events

The HTTP request will contain a topic header that can be used to route the request without parsing the body. The body of all webhook requests will have the following format:

{
  "topic": "topic.name",
  "data": <topic-dependent>
}

The format under “data” will differ by topic and will generally contain the most up to date version of whatever resource type the event is about.

It currently emits the following topics:

order.created - Order data
order.updated - Order data
order.exception.created - Order exception data
order.cancellationrequest.created - Order cancellation request data
order.returnrequest.created (beta) - Order return request data
order.returnrequest.item-approved (beta) - Order return request data
order.returnrequest.item-denied (beta) - Order return request data
asset.created - Asset data
asset.updated - Asset data
invoice.created - Invoice data
offer.updated - Offer data

Topics marked (beta) are in beta and are delivered only to webhooks enrolled in the beta program. Contact Sibi to opt in.

Testing Webhooks

We have a webhook testing tool available that you can use to send test events. You can supply any secret you want to use for testing. It provides a number of example payloads you can emit, and you can alter them to test different scenarios. It will reject any payloads that don’t match the event schemas, so all events emitted by the tool should be representative of the events you’ll receive from Sibi.