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.

Track failures

Have some error monitor in place that can detect unsuccessful deliveries so you can deal with them before it starts to effect your application. If Knoma notices an increase in unsuccessful deliveries, you'll be notified by email.

Handle duplicates

Although webhooks are designed to minimise duplicate webhook events, it is still possible to receive the same event more than once. Your application should handle webhook events using idempotent operations; that is, receiving the same webhook event a second time in a row should have no additional effect.

Order isn't guaranteed

It's possible that you'll receive, for example a loan_application_created event after a loan_application_updated event. For critical operations, it's recommended that your application fetches the latest version of the webhooks resource via the API.

Implement reconciliation jobs

Your app shouldn't rely solely on data provided in webhooks by name. For critical operations, it's recommended that your application fetches the latest version of the webhooks resource via the API.

Retries

If we have any issues delivering a webhook, we will keep retrying (with exponential falloff). If we can't reach the target URL within 3 days the event will stop trying.

NOTE: A successful response must have a 200 level status code. Receiving any other response code (or a connection error) will result in a retry.