Webhooks are an essential piece of integration offered to inform your system of any updates that have been performed on resources. These webhooks are submitted machine to machine and have an at-least-once delivery guarantee.

Webhooks are crucial to getting informed about asynchronous updates or scenarios where the network is faulty and you have not yet been able to get a response. The latter scenario can also be caught through Idempotency. It is recommended that both are implemented as asynchronous processes, such as generating invoices, which will not provide any other means of identifying this action happened besides webhooks.

A webhook is marked as received on our part when an HTTP 2XX response has been provided (for example; a 200, 201, or 202). When this has not been done within 10 seconds or any other HTTP status has been replied we will retry this webhook and queue any subsequent webhooks. This is to ensure at-least-once delivery as well as the order of events. More details on the retries that follow this scenario are detailed in the Retries chapter.

Structure

Our webhooks have a general structure with a variable data property. The following fields are present in a webhook.

1. created_at: when the webhook event was created
2. type: the event type of the webhook
3. original_request_id optional: the uniquely generated ID of the request that preceded this webhook event,
4. environment: the environment from which the webhook event originates
5. data: the resource data will be put on this parameter

Event types

Event types are a combination of the resource name and the action performed, e.g. INVOICE.CREATED.

The actions for which events are sent are:

1. CREATED
2. UPDATED
3. DELETE

Resources that have webhook configurations

1. CUSTOMER
2. PLATFORM
3. PRICING_PLAN
4. PRICING_PLAN_VERSION
5. PRICING_PLAN_SUBSCRIPTION
6. PRICING_PLAN_SCHEDULE
7. QUOTE
8. QUOTE_VERSION
9. CONTACT
10. ALERT_RULE
11. METER
12. METER_PROPERTY
13. METER_VALUE
14. METER_VALUE_CALCULATION
15. BILLABLE_METRIC
16. PRODUCT
17. PRODUCT_ITEM
18. PRODUCT_CATEGORY
19. BILLING_ENTITY
20. FEATURE
21. PAYMENT_ACCEPTOR
22. INVOICE
23. FILE_PROCESSING_SETTINGS
24. WEBHOOK
25. FILE

Configure webhooks

Configuration of webhooks can be managed through API, or Desk (coming soon). For a webhook to work a URL needs to be exposed in your application. We recommend this URL to be an HTTPS endpoint with TLSv1.2 or TLSv1.3. Alongside the URL the following additional options can be configured:

1. included_actions: for which resources actions this webhook should be applied (like CUSTOMER.CREATED)
2. excluded_actions: which resources actions should be excluded from this webhook
3. active: this webhook can be enabled/disabled

For configuration of webhooks by API please refer to the API Reference: Create a web hook

Webhooks security

Authentication

In order to protect the exposed endpoint on your part from any malicious activity there are two forms of authentication that can be included when sending a webhook. These two forms are:

1. API key
2. Username/password combination

API Key

An API key can be stored in combination with an optional header field that will be sent along with the payload. The custom header field will be used to put the API key in, if omitted the field will be put in the X-API-KEY header.

Username/password

A username-password combination can be stored and will be passed along as a basic auth configuration.

Payload integrity

📘

Obtaining a secret requires an additional step after the webhook is created, this currently only available through API, this is done through the Get a new webhook secret, this rolls the current token

In order to verify the integrity of the webhook payload as well as prevent man-in-the-middle attacks a webhook secret can be configured.

This will result in the webhook containing two additional headers:

1. X-PAYLOAD-SIGNATURE-TIMESTAMP: that indicates the time when the signature was created. This can be used to not accept any webhook coming in that is older than a defined window, our recommendation would be to block anything older than 5 minutes.
2. X-PAYLOAD-SIGNATURE: the actual signature of the payload. This may contain more than one signature.

After the signature timestamp has been checked and deemed valid the signature itself can be split into the comma (,) character.

This will result in at least one signature that is a key value pair of the version and the signature, for example:

v1=6DEA8E1EE12473F99776783FD36A430C0744C0C959085EB2D14061BE2A54729E

The signature is calculated with the HMAC SHA256 protocol. Verification can be done by concatenating the provided timestamp from the X-PAYLOAD-SIGNATURE-TIMESTAMP header as a string (according to ISO8601 standard) with the payload separated by a period (.).

Rolling webhook secret

A webhook secret can be rolled and will result in the signature being calculated for the new secret as well as the previous secret for up to 24 hours. This will ensure you have a sufficient amount of time to configure the new secret.

Retries

Whenever a webhook is submitted and not accepted within 10 seconds with HTTP 2XX status the webhook will be resent in an increasing interval:

1. 2 minutes
2. 4 minutes
3. 8 minutes
4. 16 minutes
5. 32 minutes
6. 1 hour
7. 2 hours
8. 4 hours
9. 8 hours

After which we will keep on retrying every 8 hours. If a webhook is not accepted within 7 days, it will not be retried.

🚧

Important to realize

It is recommended that you accept the webhook before processing, this might otherwise result in a timeout on our part and the webhook being sent again.