Webhooks are configured via the webhook parameter of /link/token/create. When specifying a webhook, the URL must be in the standard format of http(s)://(www.)domain.com/ and, if https, must have a valid SSL certificate.

Webhook retries

If there is a non-200 response or no response within 10 seconds from the webhook endpoint, Deck will keep attempting to send the webhook for up to 24 hours. Each attempt will be tried after a delay that is 4 times longer than the previous delay, starting with 30 seconds.

To avoid unnecessary retries, Deck won't retry webhooks if we detect that the webhook receiver endpoint has rejected more than 90% of webhooks sent by Deck over the last 24 hours.

Best practices for applications using webhooks

You should design your application to handle duplicate and out-of-order webhooks. Ensure idempotency on actions you take when receiving a webhook. If you drive application state with webhooks, ensure your code doesn't rely on a specific order of webhook receipt.

If you (or Deck) experience downtime for longer than Deck's retry period, you will lose webhooks. If you use webhooks for state transitions, ensure your application can self-heal by requesting Item state from Deck's other endpoints if a webhook is not received within a window. All data present in webhooks is also present in our other APIs.

It's best to keep your receiver as simple as possible, such as a receiver whose only job is to write the webhook into a queue or reliable storage. This is important for two reasons. First, if the receiver does not respond within 10 seconds, the delivery is considered failed. Second, because webhooks can arrive at unpredictable rates.