Hookdeck
Destinations overviewCreate a destinationSet a rate limitEdit a destinationArchive a destinationUnarchive a destination

Destinations overview

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

Destinations

HTTP vs CLI

HTTP destinations route webhooks to HTTP endpoints, whereas CLI destinations route webhooks only to local testing environments where a CLI client is present and connected.

The CLI setting is particularly useful when working on endpoints that have not yet been deployed. When enabled, webhooks are routed to the destination's CLI Path on your local server.

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.

Read our CLI and HTTP View tutorial

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

Handling webhook events from Hookdeck

Receiving webhook events

Any destination that handles webhooks from Hookdeck must accept HTTP POST requests. If your workspace does not have the static IP add-on enabled, requests may arrive from any arbitrary IP.

When routing a webhook to a destination, Hookdeck preserves the original request's headers, body, query string, and path. Exceptions to 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 webhook
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 query string ?key1=value1, and the destination URL is set to example.com/webhooks?key2=value2, the destination will receive query string ?key2=value2.

Path

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

For example, if a provider is set up to send webhooks 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 webhook events

When setting up a destination endpoint to respond to webhook 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.