​
Receiving Events via Webhook

To start receiving events via webhook, email us the URL you’d like Sibi to send requests to. We will POST to this endpoint.

​
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. When you email us your endpoint URL you can send us a secret, or request that we generate a secret on your behalf that we will later send you. If you want to generate this secret yourself, it should be a random string with high entropy. One way to generate this would be to run ruby -rsecurerandom -e 'puts SecureRandom.hex(20)', for example. If you choose to use a secret, we will calculate a sha256 hash using your secret and set it in the HTTP_X_SIBI_SIGNATURE_256 http header sent with the webhook. For an example of how to verify this hash 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.

​
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:

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