​
Introduction

Webhooks are what we use to send information back to our users. The person interacting with our endpoints 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.

​
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 URL. Note: We currently support a single Webhook URL per account. Updating it on any Job will update it for all other Jobs for all other Links as well. Configure your webhook URL in the Dashboard

​
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.
  2. Webhooks can arrive at unpredictable rates.