Webhooks are reliable HTTP POST callbacks. By subscribing to our webhooks, you can listen for events such as new signups and contract changes to keep your system synchronized to billwerk. This is particularly useful for using our ready-to-use customer portal and signup pages.

Security & Reliability

Reliability is achieved by repeating the request until it is responded to with a 200 OK, 201 Created, 202 Accepted or 204 NoContent success response. Ensure your application only returns a success code after it has persisted important information. We will repeat the request a dozen times until we will drop the hook. Repeated requests will contain the header X-Retry-Count with the number of retries. E.g. X-Retry-Count:1 for the first retry.

Redirects 301 Moved Permanently will be followed until we reach one of the codes above.

📘

Note

If your application does not reply within 10 seconds we assume a timeout and we repeat the request. The delay between two attempts doubles after every failed attempt, so keep in mind that webhooks could be up to two days old!

A common approach to secure webhooks is to use HMAC-SHA* message signing. While that is not a bad method, it forces you to provide SSL on your site, validate the request hash and read the data from the webhook. That drags versioning and security issues along, and it must be secured against replay attacks.

In contrast, billwerk webhooks only contain an Event field and, depending on the event, an id field such as ContractId. That means you will have to query the billwerk API to retrieve the current state of the referenced object in your handler. This makes it possible to receive webhooks on non-SSL pages, and it is easier to handle hooks that are delayed or potentially arrive in the wrong order. So, even though webhooks use POST and are not generally required to, we recommend your webhook handler be idempotent.