Webhook Events

Webhooks can be use to get notified about events that happen in your StrawBlond organization.

You configure webhooks from the Organization Settings, which provides a user interface for registering your webhook endpoints.

Webhooks are HTTPS-only

All webhook events are sent via HTTPS, thus your receiving Endpoint must support HTTPS.

Receiving webhook events

All webhook data will be sent as JSON using an application/json content type. The data shape always looks like this:

{
    "id": "<unique-id>",
    "event": "<event-type>",
    "created": 1663762684, // UNIX timestamp
    "test": false, // `true` if this is a test event
    "data": {
        // The associated object (eg. invoice, expense)
    }
}

Respond quickly

After receiving a webhook using an HTTPS endpoint, it's important to respond to the request with a 200 OK as quickly as possible.

A common pattern is to store the payload in a message queue for later processing by a background worker. This reduces the chance of the request timing out and the webhook delivery counting as a failure.

Verify incoming webhook requests

StrawBlond signs all webhook requests by including a signature X-StrawBlond-Webhook-Signature header. This allows you to verify that the events were actually sent by StrawBlond, not by a thrid party.

When creating a new webhook endpoint, you are given a Secret you can use to verify signatures.

To verify the incoming webhook, you need to compute an HMAC hash of the payload using SHA-256 and compare it with the included signature from the request header. Use the your Secret as the key.

$signature = hash_hmac('sha256', $payload, $secret);

Your computed hash must be the same as the signature from the request header.

Using libraries

If you don't want to verify incoming webhook request yourself, we reccommend using a dedicated webhook client library.

• Laravel Webhook Client (PHP, Laravel)

Testing webhooks on localhost

To setup a webhook you need to provide StrawBlond an URL that is publicly available over the internet.

In order to receive webhook calls on your localhost, you can use services like Expose or ngrok to create a secure tunnel to your local machine.

You can manually send test webhook events using the StrawBlond webhooks UI.