Destinations

A destination is any endpoint to which your events can be routed.

Destination types

Hookdeck presently supports three destination types:

  • HTTP: a public endpoint that you want to route your events.
  • CLI: destinations route events only to local testing environments where the Hookdeck CLI is installed and connected
  • Mock API: A Mock API endpoint that accepts all API requests sent to it. You can use it to start accepting requests and observe the incoming events without writing a single line of code.

Because the CLI environment is reserved for testing, events routed to the CLI employ neither a connection's ruleset nor its custom rules. This includes rate limits, retries, and issues.

Rate limiting

Hookdeck lets you set a rate limit for your destination. This limit can help shield your server from volume spikes.

There are several common scenarios where setting a rate limit on a destination can prove useful:

  • Your receiving API enforces a rate limit policy that rejects requests exceeding a predetermined maximum rate of arrival.
  • You perform a bulk update operation within the sending platform, like bulk updating all your products in Shopify.
  • The sending platform, having experienced an outage, has accumulated a backlog of events that it tries to deliver all at once.
  • You have a sudden burst in usage because of a new customer or specific world events, like Black Friday/Cyber Monday.

Handling events from Hookdeck

Receiving events

By default, Hookdeck sends events to destinations via HTTP requests using the original request method. You can customize the HTTP method in the destination configuration when creating or editing your destinations. If your workspace does not have the static IP add-on enabled, requests may arrive from any arbitrary IP.

By default, requests sent by Hookdeck are verified using the Hookdeck Signature. You can use this signature to verify that the events are coming from Hookdeck. You can customize this authentication strategy to another mechanism that fits your needs better.

Destination authentication

When routing a request to a destination, Hookdeck preserves the original request's headers, body, query string, and path. the finer details of this rule are listed below.

Headers

In addition to the request's original headers, Hookdeck appends the following additional headers:

HeaderDescription
x-hookdeck-attempt-countEvent attempt count
x-hookdeck-eventidHookdeck event ID
x-hookdeck-event-urlURL of event on the Hookdeck dashboard
x-hookdeck-original-ipThe IP of the client that sent the original request
x-hookdeck-signatureHookdeck HMAC signature (sha256, base64 encoded)
x-hookdeck-source-aliasAlias of the source that received the request
x-hookdeck-verifiedBoolean representing whether Hookdeck verified the original request

Query string

Hookdeck will never alter the query string of the original request unless a query string is specified in the destination URL.

For example, if Hookdeck receives a request with the query string ?key1=value1, and the destination URL is set to example.com/webhooks?key2=value2, the destination will receive the query string ?key2=value2.

Path

By default, Hookdeck preserves any path appended to the Hookdeck URL when routing an event to its destination.

For example, if a provider is set up to send events to https://events.hookdeck.com/e/src_abcxyz/path/to/forward and your destination URL is https://www.example.com/webhooks, then your destination will receive the request at https://www.example.com/webhooks/path/to/forward.

To prevent this behavior, disable path forwarding on the destination.

Responding to event requests

When setting up a destination endpoint to respond to events received from Hookdeck, please keep the following requirements in mind.

Status codes

Whenever possible, a destination should respond to each request with a status code that reflects the actual state of the system. When an operation is processed, respond with an HTTP 2XX for success, or an HTTP 4XX - 5XX for failure.

The more specific your error codes, the more helpful Hookdeck will be for troubleshooting and resolving issues.

Taking action

Hookdeck works best when the destination server takes action on the request before responding to it, rather than simply returning an HTTP 2XX and queueing the event.

Allowing the destination server to take all relevant actions before returning a status code increases visibility and facilitates recoverability inside Hookdeck.

Timeout

The destination must respond to a request within 60 seconds, or the attempt will be given the error code TIMEOUT and will be marked as failed within Hookdeck. It can then be retried.

If the standard 60-second timeout is insufficient for your needs, contact us to request an increase.

Create a destination

Creating a destination allows Hookdeck to begin routing events to an external endpoint.

To create a destination, follow the instructions to create a connection.

To fan out a single source to multiple destinations, create a connection on an existing source.

Set a rate limit

Setting a rate limit allows you to define a maximum rate at which Hookdeck will send requests to a destination. Updating or adding a rate limit will take effect within the next minute.

When you don't set a rate limit, Hookdeck will apply your workspace quota limit. You can see you current plan quota in your dashboard. See the pricing page for quota limits for each plan.

Destination rate limit popup

  1. Open the Connections page.
  2. Click the HTTP Destination you want to rate limit.
  3. Toggle the Rate Limit switch.
  4. Input a rate limit value, and choose a unit of per second, per minute, or per hour.
  5. Click Save .
PUT /destinations/:id

Add destination authentication

Configure how requests to destinations should be authenticated. By default, new destinations use the Hookdeck Signature verification method.

  1. Open the Connections page.
  2. Click the destination you want to authenticate.
  3. Click Open Destination .
  4. Under Destination Configuration, select the appropriate authentication method from the Authentication dropdown.
  5. Enter the information required by the authentication method (HMAC, Basic Auth, API Key, or Bearer Token).
  6. Click Save .
PUT /destinations/:id

All secrets are AES encrypted.

Edit destination authentication

Edit a destination to update the authentication method or change the credentials.

  1. Open the Connections page.
  2. Click the destination you want to edit the authentication method for.
  3. Click Open Destination .
  4. Under Destination Configuration, change the authentication method via the Authentication dropdown along with related credentials.
  5. Click Save .
PUT /destinations/:id

Edit a destination

Editing a destination lets you change its name, destination URL, rate limit, path forwarding, and other properties.

Open the Connections page. From the connections page, you can edit the destination quickly via the dialog or via destination advanced configuration.

Edit destination dialog

Click the Destination you want to edit to open the destination dialog.

From the destination dialog, you can edit the Destination Name. Additionally, you can make the following edits depending on the selected Destination Type:

HTTP

  • Endpoint URL: Set the HTTP endpoint the request will be forwarded to.
  • Rate Limit: Configure a rate limit.

CLI

  • CLI Path: Path to forward the request to on localhost. For example, /webhook.

Mock API

Edit destination advanced configuration

Click the Destination you want to edit and click the Open Destination button and scroll to the Destination Details section.

To edit the destination's name, change the text in the Destination Name field. You can also optionally provide a description for your destination.

Additional options are available depending on the Destination Type that is selected:

HTTP

  • Endpoint URL: Set the HTTP endpoint the request will be forwarded to.
  • Rate Limit: Configure a rate limit.
  • Path Forwarding: Allow or disallow path forwarding, toggle the switch to Enabled or Disabled.
  • Custom HTTP Method: To customize the HTTP method, select the desired method in the Custom HTTP Method dropdown.
  • Authentication: Set the required outbound HTTP request authentication method from the dropdown.

CLI

  • CLI Path: Path to forward the request to on localhost. For example, /webhook.
  • Path Forwarding: Allow or disallow path forwarding, toggle the switch to Enabled or Disabled.
  • Authentication: Set the required outbound HTTP request authentication method from the dropdown.

Mock API

  • Rate Limit: Configure a rate limit.
  • Path Forwarding: Allow or disallow path forwarding, toggle the switch to Enabled or Disabled.
  • Custom HTTP Method: To customize the HTTP method, select the desired method in the Custom HTTP Method dropdown.
  • Authentication: Set the required outbound HTTP request authentication method from the dropdown.

Once you've made your desired edits, click Save .

PUT /destinations/:id

Once a destination's settings have been updated, the new values take effect immediately across your workspace.

Customize destination authentication strategy

There are several reasons why you may want to customize the authentication strategy sent by Hookdeck to your destinations. Maybe you have your own authentication strategy you'd like to use instead of Hookdeck's SHA-256 signature. Or maybe you're routing requests to another service that requires a different authentication mechanism.

Regardless, you can customize this authentication in your destination configuration.

Destination authentication

Archive a destination

Archiving a destination temporarily halts the routing of events to the associated endpoint.

This process also archives all the connections that are associated with that destination.

  1. Open the Connections page.
  2. Click the destination you wish to archive.
  3. Click ••• button in the bottom right corner of the popup.
  4. Click Archive Destination .
PUT /destinations/:id/archive

Once a destination has been archived, it will disappear from your list of destinations and the Connections page. It can still be found in your list of destinations when creating a connection or searching for destinations.

Unarchive a destination

Unarchiving a destination makes that destination available for use within a new or existing connection.

  1. Open the Connections page.
  2. Click the archived destination you wish to unarchive.
  3. Click ••• button in the bottom right corner of the popup.
  4. Click Unarchive Destination .
PUT /destinations/:id/unarchive

Once a destination is unarchived, it reappears in your list of destinations.

Delete a destination

Deleting a destination permanently disables that destination and removes it from your Connections page. Associated event data is retained for the remainder of your retention window.

This process also deleted all the connections that relies on the destination.

  1. Open the Connections page.
  2. Click the destination you wish to delete.
  3. Click ••• button in the bottom right corner of the popup.
  4. Click Delete Destination .
  5. Click Delete in the confirmation dialog.
DELETE /destinations/:id

Your deleted destination will no longer receive any events.