Destinations overview
A destination is any endpoint to which your webhooks can be routed.
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.
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
By default, Hookdeck sends webhook events to destinations via HTTP POST requests. 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.
Webhooks sent by Hookdeck are verified by calculating a digital signature. You can use this signature to verify that the webhooks are coming from Hookdeck. You can customize this authentication strategy to another mechanism that fits your needs better.
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:
| Header | Description |
|---|---|
x-hookdeck-attempt-count | Event attempt count |
x-hookdeck-eventid | Hookdeck event ID |
x-hookdeck-event-url | URL of event on the Hookdeck dashboard |
x-hookdeck-original-ip | The IP of the client that sent the original request |
x-hookdeck-signature | Hookdeck HMAC signature (sha256, base64 encoded) |
x-hookdeck-source-alias | Alias of the source that received the webhook |
x-hookdeck-verified | Boolean 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.