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.

Delivery rate

Hookdeck lets you set a max delivery rate for your destination. This limit can help shield your server from unexpected increases in event volume and allow you to allocate your resources to meet a dependable ingestion rate.

There are several common scenarios where setting a maximum delivery 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 project 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 max delivery rate

Setting a delivery rate allows you to define a maximum rate at which Hookdeck will send requests to a destination.

Events beyond your delivery rate and will be queued and shown as "Pending".

The options for deliver rate are:

  • per second: The maximum number of events per second.
  • per minute: The maximum number of events per minute.
  • per hour: The maximum number of events per hour.
  • concurrent: The maximum number of simultaneous requests that Hookdeck will have open to the Destination at any time. The rate of delivery in this scenario is determined by the concurrent rate you set, how quickly your server responds to the request and closes the connection (delivery latency), and your Hookdeck throughput limit.

For per hour and per minute rate limits, the delivery will be evenly spread over the time period. For example a rate of 4 per minute is equivalant to 1 every 15 seconds. Even if all 4 events come exactly at the same time, there will be delayed by 15 seconds each (beyond the first one).

Regardless of your configured delivery rate Hookdeck will apply your project throughput limit. You can see you current throughput quota in your Quotas project page. Learn more about project throughput.

Destination rate limit popup

  1. Open the Connections page.
  2. Click the HTTP Destination you want to update.
  3. Toggle the Max delivery rate switch.
  4. Input a delivery rate 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, delivery rate, 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.
  • Max Delivery Rate: Configure a delivery rate.

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.
  • Max Delivery Rate: Configure a delivery rate.
  • 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

  • Max Delivery Rate: Configure a delivery rate.
  • 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 project.

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

Disable a destination

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

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

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

Once a destination has been disabled, 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.

Enable a destination

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

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

Once a destination is enabled, 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.