Destinations

What's a Destination

A Destination is used to define the URL where your webhooks should be sent. Generally, this should be labeled after the service or a specific method on your service. For example, "Order Service", "Internal API" or "Update Order".

Each Destination has a webhook URL which is the endpoint Hookdeck will be sending HTTP POST requests. The original request headers and the data are preserved. Additionally, Hookdeck will also append metadata to the request.

HTTP vs CLI destinations

Destinations mode can be toggled between HTTP and CLI ONLY. A CLI ONLY destination will not send any webhook events to an HTTP URL and will instead only be available to connected CLI clients when the webhook is received.

A CLI ONLY destination does not have a URL endpoint and instead allows for a CLI path value used to configure to which path the request will be forwarded to on your local server. Additionally, Throttled Delivery is not available for CLI ONLY destinations.

An HTTP destination requires an HTTP URL for webhooks to be forwarded to. However, an HTTP destination can still be connected to by the CLI, and the CLI Path will be automatically parsed from your HTTP URL. You can disabled access from the CLI by unchecking the "Allow CLI connections" checkbox.

Additionally, any events forwarded to the CLI will not apply to your connection ruleset. This prevents unwanted automatic retry once the CLI is closed and silences any alert.

Throttled delivery using a rate limit

Each destination can be configured to deliver at a specific rate. You can enable and configure the destination rate limit to make sure you do not receive more requests than the configured value. This is especially useful to deal with large increases in the volume of webhooks. There are multiple reasons you could reason many more webhooks than you expect:

• You perform a bulk update operation in the platform sending the webhook, like bulk updating all your products in Shopify;
• The webhook provider has an outage and accumulated a backlog of webhooks there will try to deliver at once;
• You have a sudden burst in usage because of a new customer, a time of the year (Black Friday), etc.

In general, to protect your infrastructure we recommend setting a sensible ceiling for the rate limit. Hookdeck will queue the attempts and deliver them as fast as possible while respecting your configuration.

Receiving webhook events

To receive your webhook events you will need an HTTP server listing on a given endpoint for HTTP POST request accepting Content-Type: application/json

A simple NodeJS implementation using ExpressJS would be

const express = require('express');
const app = express();
const port = 5050;

// If you expect webhook data as JSON
app.use(express.json());
// If you expect webhooks as plain text
app.use(express.text());
// If you expect webhooks as application/x-www-form-urlencoded
app.use(express.urlencoded({ extended: true }));

const processRoute = (req, res) => {
  console.log('query', req.query); // {test: 1} if a query string ?test=1 is set
  console.log('path', req.path); // /webhooks/path/to/forward if request URL is https://events.hookdeck.com/e/src_xxxxxxxxxxxxxxxxxxxxxxxx/path/to/forward
  console.log('body', req.body); // {key: "value"} if raw json body is {"key": "value"}

  res.send('Server received a webhook!');
};

app.post('/webhooks/*', processRoute);
app.post('/webhooks', processRoute);

app.listen(port, () => {
  console.log(`Example app listening at http://localhost:${port}`);
});

Create a Destinaton

To create a Destination follow these two steps.

• In the upper right corner of the dahsboard, choose Destination, then click Create

• Fill in the details in the Create Destination form

Edit a Destination

You can edit a Destination by selecting the edit button from the destination card options menu:

Archive a Destination

You have the option to archive a Destination you do not use anymore.

You can unarchive a Destination if you decide to want to use it again.