Introduction

Webhooks are what we use to send information back to our users.

The user making the call needs to set up a Webhook URL (i.e. their own endpoint) which will act as a webhook listener that can receive POST requests, then provide this endpoint URL to Deck as described in the next section below.

However, we understand that this can be tedious.
You can contact us at any time to have a Webhook URL assigned to your team. This URL will be static and used every time data is sent to that team. Every team can have its own Webhook URL. To update it, you can use /api/v1/connection/webhook/update with an Access token.

Configuring webhooks

Webhooks are configured via the Dashboard. 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.

If you go to the Links page of your Dashboard and click any of the Links you have created so far, you will see the option to configure your webhook in the Output section.

Webhook retries

If there is a non-200 response, or no response within 10 seconds, from the user's webhook endpoint, Deck will try to resend the webhook up to 3 times. Each retry will be attempted using a decorrelated jitter backoff algorithm with a median of 30 seconds for the first try.

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; 1) if the receiver does not respond within 10 seconds, the delivery is considered a failure, and 2) because webhooks can arrive at unpredictable rates.