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. Make sure your application only returns a success code after it has persisted important information. We'll repeat the request a dozen times until we will drop the hook. Redirects 301 Moved Permanently will be followed until we reach one of the codes above.

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 out of 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 that you'll 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's easier to handle hooks that are delayed or potentially arrive in the wrong order. So, even though webhooks use POST and aren't generally required to, we recommend your webhook handler be idempotent.