Implementing a Webhook Handler

When implementing a webhook endpoint, clients must stick to the following rules to avoid failed event delivery:

  1. The endpoint must respond to the webhook event with an HTTP status code in the range 2xx. Any other status code, including redirecting with a 3xx code, is a failure.

  2. The endpoint must respond quickly to the webhook event request. Make sure to respond with a 2xx code before starting any slow processes or waiting for asynchronous work to complete.

When a failure occurs, whether due to a network error, a non-2xx status code, or a timeout, Everee tries to deliver the event multiple times over the next several days. Retries are delayed with an exponential backoff, which causes each retry attempt to delay longer than the previous attempt was delayed.

After several days of failures, Everee will stop trying to deliver the webhook event, and information about the relevant object will need to be fetched from the Everee API on demand.

It’s possible to occasionally receive the same webhook event more than once. Clients should ensure their webhook endpoint is idempotent by keeping track of the unique ID of the event (in the payload's id property). If a duplicate event is received, clients should skip processing it and respond with an HTTP status code 2xx.