A webhook notifies your application when an event happens in your By Bits platform. Webhooks are particularly useful for real-time events like when a journey has been completed or a statement has been generated. Think of it like an alert between systems.

Your application will consume a webhook via an open POST endpoint that you create. Your endpoint can then marshal an event like sending an email, sms or push notification (i.e. journey completed). The endpoint is the same for all webhook events but will deal with the events differently dependent on the webhook code.

Your application webhook POST endpoint can be created in the By Bits admin dashboard for each product.

Testing webhooks

You application webhook endpoint can be tested within the By Bits admin dashboard.

Navigate in the top-right to Products > Product View, then add the webhooks url and enable webhooks. There is a test button that will fire a webhook event to your application immediately.

Alternatively you can hit the health endpoint directly and it will also fire a webhook event to your application.

// Example Request
{
    "url": "https://api.bybits.co.uk/health",
    "headers": {
        "client_secret": "11111-22222-33333-44444",
        "client_id": "11111-22222-33333-44444",
        "environment": "production"
    },
    "method": "GET"
}
// Example Webhook Event Fired
{
    "code": "usage_device_unplug",
    "data": {
        "version": "Running version 0.1.0",
        "service": "rating"
    },
    "environment": "production",
    "created": 1597238502
}

Production webhooks

The production webhooks need to have your application POST endpoints to consume the events defined in the By Bits admin dashboard. This is set as part of the product definition. All webhook events will be sent to this endpoint as long as it is enabled. Your application can filter an event it isn't interested in, or filter out on an environment basis (i.e. sandbox or production)

Webhooks are currently fire and forget. We do not try to retry sending the webhooks. Your application should persist or queue all inbound webhook events. We have a 2500ms timeout set for a 200 response.

A list of all available webhooks is available within the APIs documentation.