​
Introduction

A webhook is a way for one web application to send real-time data to another web application automatically when a specific event occurs. We use them to communicate Job results to you by sending the fetched data, notifying you of errors, or providing links to retrieve documents, among others. 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.

​
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.
If you change the webhook URL while a connection is open, the URL will not be udated until the connection is closed.
In other words, the change in URL will only affect connections made after the change.
Configure your webhook URL in the Dashboard

​
Payload Structure

The payload of our successful webhooks will contain multiple, if not all, of the following properties as a JSON object: job_guid allows for Job identification.
output contains the data retrieved.
webhook_type always is Job.
webhook_code always is the name of the Job it is coming from.
environment indicates the environment of the Job, either Sandbox or Production. Here is an example of a webhook received from the MakePayment Job. 
{
    "job_guid": "a4e67899-9b8a-481c-h6fe-ee3c6399c0e2", 
    "output": {
      "success": true,
      "message": "",
      "service_fee": 2.30,
      "confirmation_id": "767945634509"
    },
    "webhook_type": "Job",
    "webhook_code": "MakePayment",
    "environment": "Production"
}

​
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.