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

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.

HTTP Method

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.

Authentication

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.

Hookdeck IP addresses

If your project does not have the static IP add-on enabled, requests may arrive from any arbitrary IP.

Headers

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

You can change the x-hookdeck prefix to a custom prefix in the Project settings.

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://hkdk.events/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.

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.

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.

Controlling retries

You can configure the status codes that trigger a retry and you can return a Retry-After HTTP header from the destination to provide fine-grained control of retry timing.

See Configuring automatic retries for more information.

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.

{
  "name": "my-new-api"
}

{
  "id": "des_YDn6Awgm7Zp8iQ0jSGw4GCme",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "name": "my-new-api",
  "type": "MOCK_API",
  "disabled_at": null,
  "updated_at": "2021-08-02T14:12:56.960Z",
  "created_at": "2021-08-02T14:09:56.116Z",
  "config": {
    "url": "https://mock.hookdeck.com",
    "rate_limit": null,
    "rate_limit_period": "second",
    "path_forwarding_disabled": false,
    "http_method": "POST",
    "auth_type": "HOOKDECK_SIGNATURE",
    "auth": {}
  }
}

Add destination authentication

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

{
  "name": "my-new-api"
}

{
  "id": "des_YDn6Awgm7Zp8iQ0jSGw4GCme",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "name": "my-new-api",
  "type": "MOCK_API",
  "disabled_at": null,
  "updated_at": "2021-08-02T14:12:56.960Z",
  "created_at": "2021-08-02T14:09:56.116Z",
  "config": {
    "url": "https://mock.hookdeck.com",
    "rate_limit": null,
    "rate_limit_period": "second",
    "path_forwarding_disabled": false,
    "http_method": "POST",
    "auth_type": "HOOKDECK_SIGNATURE",
    "auth": {}
  }
}

All secrets are AES encrypted.

Edit destination authentication

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

{
  "name": "my-new-api"
}

{
  "id": "des_YDn6Awgm7Zp8iQ0jSGw4GCme",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "name": "my-new-api",
  "type": "MOCK_API",
  "disabled_at": null,
  "updated_at": "2021-08-02T14:12:56.960Z",
  "created_at": "2021-08-02T14:09:56.116Z",
  "config": {
    "url": "https://mock.hookdeck.com",
    "rate_limit": null,
    "rate_limit_period": "second",
    "path_forwarding_disabled": false,
    "http_method": "POST",
    "auth_type": "HOOKDECK_SIGNATURE",
    "auth": {}
  }
}

Edit a destination

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

{
  "name": "my-new-api"
}

{
  "id": "des_YDn6Awgm7Zp8iQ0jSGw4GCme",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "name": "my-new-api",
  "type": "MOCK_API",
  "disabled_at": null,
  "updated_at": "2021-08-02T14:12:56.960Z",
  "created_at": "2021-08-02T14:09:56.116Z",
  "config": {
    "url": "https://mock.hookdeck.com",
    "rate_limit": null,
    "rate_limit_period": "second",
    "path_forwarding_disabled": false,
    "http_method": "POST",
    "auth_type": "HOOKDECK_SIGNATURE",
    "auth": {}
  }
}

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.

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.

{
  "id": "des_YDn6Awgm7Zp8iQ0jSGw4GCme",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "name": "my-new-api",
  "type": "MOCK_API",
  "disabled_at": null,
  "updated_at": "2021-08-02T14:12:56.960Z",
  "created_at": "2021-08-02T14:09:56.116Z",
  "config": {
    "url": "https://mock.hookdeck.com",
    "rate_limit": null,
    "rate_limit_period": "second",
    "path_forwarding_disabled": false,
    "http_method": "POST",
    "auth_type": "HOOKDECK_SIGNATURE",
    "auth": {}
  }
}

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.

{
  "id": "des_YDn6Awgm7Zp8iQ0jSGw4GCme",
  "team_id": "tm_nlcetVe8k1lMAY0KR0OxNuHr",
  "name": "my-new-api",
  "type": "MOCK_API",
  "disabled_at": null,
  "updated_at": "2021-08-02T14:12:56.960Z",
  "created_at": "2021-08-02T14:09:56.116Z",
  "config": {
    "url": "https://mock.hookdeck.com",
    "rate_limit": null,
    "rate_limit_period": "second",
    "path_forwarding_disabled": false,
    "http_method": "POST",
    "auth_type": "HOOKDECK_SIGNATURE",
    "auth": {}
  }
}

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 deletes all the connections that rely on the destination.

{
  "id": "des_YDn6Awgm7Zp8iQ0jSGw4GCme"
}

Your deleted destination will no longer receive any events.