Webhooks

Webhooks are outbound user-defined HTTP callbacks that originates from Tirix in response to a defined event. An example could be that a shipment has been sent or an article has decreased in stock. When that event occurs and a webhook is configured that matches the events circumstances, Tirix makes an HTTP request to the URL configured for the webhook.

Polling vs subscribing

Webhooks is an alternative to polling for information.

Polling means that you on intervals (every {n} minutes) request information from a service.

The reverse of polling would be to setup that the service on invervals sends information to an external system.

Webhooks by contrast is triggered by an internal event, which has various implications.

Everytime a webhook is triggered, something has happened. What has happened is what is being transmitted to the webhook URL.

Security

Webhook requests made by Tirix include a Signature header. It contains a string generated by hashing the data sent to your webhook endpoint with a secret key. The secret key is a random string that is generated when you create a webhook.

Verifying a signature:

var crypto = require('crypto');
var secret = /* webhook secret */;
var signature = /* signature header */;
var body = /* webhook body */;

var hmac = crypto.createHmac('sha256', secret).update(body).digest('hex');
var signature_verified = (hmac == signature);

$secret = /* webhook secret */;
$signature = /* signature header */;
$body = /* webhook body */;

$hmac = hash_hmac('sha256', $body, $secret);
$signature_verified = hash_equals($signature, $hmac);

Schema: Webhook

Property	Type	Description
id	ObjectId	Unique identifier
name	String	Optional naming of the resource
event	String (Event)	Event type that should trigger the webhook
url	String	Endpoint which Tirix should make its HTTP request to
enabled	Boolean	Webhook only triggers if the enabled property is set to 'TRUE'
tenant	ObjectId	Tenant identifier
secret	String	Random string used to verify a webhook signature
created	Date	Time when the webhook was created
updated	Date	Time when the webhook was last modified

Enum: Event

Event	Description
webhook.created	A new webhook has been created
webhook.modified	A webhook has been modified
webhook.deleted	A webhook has been deleted
article.created	A new article has been created
article.stock_changed	The stock of an article has changed
delivery.created	A new delivery has been created
delivery.modified	A delivery has changed
delivery.sent	A delivery has been sent

Get a list of webhooks

If you want to retrieve a list of webhooks, use this GET request:

GET https://api.tirix.io/webhooks

Get a webhook

If you want to fetch an individual webhook, use this GET request:

GET https://api.tirix.io/webhooks/{webhook_id}

Create a webhook

If you want to create a new webhook, use this POST request:

POST https://api.tirix.io/webhooks

Modify a webhook

If you want to modify a specific webhook, use this PUT request:

PUT https://api.tirix.io/webhooks/{webhook_id}

Delete a webhook

If you want to remove a specific webhook, use this DELETE request:

DELETE https://api.tirix.io/webhooks/{webhook_id}

TIP

This request will irreversibly delete the webhook. You can alternatively suspend/resume the webhook by modifying its 'enabled' property.