The Billit API Allows you to use Webhooks. This so your integration can listen automatically to any updates and trigger reactions.
Billit usess webhooks to notify your application when an event happens in your account. These are useful to able to catch async events such as an invoice that has been paid, updated or created.
How to use the Billit Webhooks
The Billit webhooks push HTTPS calls to the registered URL provided. We will send a JSON payload to your integration. This data can be used to execute actions in you backend systems.
Steps to receive a webhook
- Create the webhook Webhook
- Handle the returned request. This payload will provide you a Secret. This secret can be used to verify incomming webhooks
- You can delete or retrieve webhooks via the API
- If needed you can refresh the Secret by using the API endpoint
The Webhooks will soon be visible in the web application.
Webhook Signatures
We sign all webhooks we send out with a signature. This Signature can be decrypted by using the Secret we provided you when creating the webhook.
Verifying signatures
The Billit-Signature header included in each webhook event contains a timestamp and a signature. The timestamp is prefixed by t= and the signature by s=.
t=1657133145,s=479f86b8baa181b97281b767b8db125cc312d18b3e611d6157571abcd539f09f
1. Extract the timestamp and signature from the signature header
Get the timestamp and signature value by splitting the string by ",".
Next you can split by "=" to get the value of the parameter.
2. Build the signature payload string
The signature payload is created by concatenating:
- The timestamp
- The character "."
- The received payload as a JSON string
For example:
1657133145.{"OrderID":12345,"EntityType":"Order", ...}
3. Compare the hash
SHA-256 hash the signature payload with the signing secret key as key. Verify the generated hash with the signature extracted from the signature header.
Optionally, you can check if the difference between the current timestamp and the extracted timestamp is within your tolerance.