Event Gateway API Reference

Get an API key

You'll need to include an API key in every API request. If you do not yet have a Hookdeck account, please sign up for a free account. Your API key is located in your project settings.

To include your API key in requests, use either Bearer Token Authentication or Basic Authentication.

Basic Authentication is deprecated and remains supported for backwards compatibility.

Create your first connection

As an example let's create a connection between a source and a destination. This will allow you to start routing events with Hookdeck.

Minimum parameters

By default, the source is assumed to be of type WEBHOOK and the destination of type HTTP.

View the full specification for the connection object here.

Verify your first connection

Verifying the connection lets you know Hookdeck is properly ingesting and processing events from your source.

Copy the unique Hookdeck URL and paste it into your API provider's HTTP URL field. Test the connection by triggering a request on your source. As soon Hookdeck receives your first request, it'll appear in your dashboard.

Congratulations! Your request & events can now be viewed, inspected, filtered, sorted, retried, and so much more using Hookdeck.

Authentication

Scope: This authentication method applies to Hookdeck REST API endpoints (e.g., /events, /requests, /sources) and Hookdeck Publish API endpoints (https://hkdk.events/v1/publish). For authentication when sending requests to a Source URL (e.g., https://hkdk.events/src_123...), see Source Authentication.

Your API key is located in your project settings, and must be included in every API request. Use either Bearer Token Authentication or Basic Authentication.

Paging

All GET endpoints that retrieve a list of resources are paged using cursor (aka keyset) pagination, which resides in the response body's pagination object.

Unless you have specified an order_by or dir, you can omit it from the next or previous set query. You only have to carry them over if you are not using the resource default.

Errors

Hookdeck uses standard HTTP response codes to indicate the success or failure of an API request.

In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing), and codes in the 5xx range indicate an error. See a more complete list of error codes here.

Rate Limits

The Hookdeck API has a rate limit of 240 request per minute, per API key. Contact us if you need your rate limit increased.

Connections

A connection lets you route webhooks from a source to a destination, using a rule.

Retrieve connections

This endpoint lists connections, or a subset of connections.

Create a connection

This endpoint creates a connection. You can create a connection's underlying source, destination, and rules with a single call by declaring an object for any of those resources. You can reuse a source or destination by referencing their ID.

Create/Update a connection

This endpoint creates a connection, or updates an existing connection by name. A connection's source and destination cannot be updated.

Count connections

Retrieve a connection

This endpoint retrieves a specific connection.

Update a connection

This endpoint updates a connection.

Delete a connection

This endpoint permanently deletes a connection. This action cannot be undone.

Disable a connection

This endpoint disables a connection. Notice that a connection is enabled by default when created. A disabled connection will no longer receive or deliver any events.

Disable a connection

This endpoint disables a connection. Notice that a connection is enabled by default when created. A disabled connection will no longer receive or deliver any events.

Enable a connection

This endpoint enables a connection that has been previously disabled. The associated source and destination will also be enabled if they were previously disabled.

Enable a connection

This endpoint enables a connection that has been previously disabled. The associated source and destination will also be enabled if they were previously disabled.

Pause a connection

This endpoint pauses a connection. A paused connection will still receive events, but those events will be marked with a status of HOLD and will be delivered only once the connection is unpaused.

Unpause a connection

This endpoint unpauses a connection. Any event with a status of HOLD will be attempted. Destination delivery rate will be respected. This operation is asynchronous, so it may take some time for all events to be QUEUED for delivery.

Sources

A source represents any third party that sends webhooks to Hookdeck.

Retrieve sources

This endpoint lists sources, or a subset of sources.

Create a source

This endpoint creates a source.

Create/Update a source

This endpoint creates a source, or updates an existing source by name.

Count sources

Retrieve a source

This endpoint retrieves a specific source.

Update a source

This endpoint updates a source.

Delete a source

This endpoint permanently deletes a source. This action cannot be undone.

Disable a source

This endpoint disables a source. A disabled source will no longer receive any events, and all connections associated with this source will also be disabled.

Disable a source

This endpoint disables a source. A disabled source will no longer receive any events, and all connections associated with this source will also be disabled.

Enable a source

This endpoint enables a source that was previously disabled.

Enable a source

This endpoint enables a source that was previously disabled.

Destinations

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

Retrieve destinations

This endpoint lists destinations, or a subset of destinations.

Create a destination

This endpoint creates a destination.

Create/Update a destination

This endpoint creates a destination, or updates an existing destination by name.

Count destinations

Retrieve a destination

This endpoint retrieves a specific destination.

Update a destination

This endpoint updates a destination.

Delete a destination

This endpoint permanently deletes a destination. This action cannot be undone.

Disable a destination

This endpoint disables a destination. A disabled destination will no longer deliver any events.

Disable a destination

This endpoint disables a destination. A disabled destination will no longer deliver any events.

Enable a destination

This endpoint enables a destination that was previously disabled.

Enable a destination

This endpoint enables a destination that was previously disabled.

Issue Triggers

Issue Triggers lets you setup rules that trigger issues when certain conditions are met.

Retrieve issue triggers

This endpoint lists issue triggers.

Create an issue trigger

This endpoint creates an issue trigger.

Create/Update an issue trigger

This endpoint creates an issue trigger, or updates an existing issue trigger by name.

Retrieve an issue trigger

This endpoint retrieves a specific issue trigger.

Update an issue trigger

This endpoint updates an issue trigger.

Delete an issue trigger

This endpoint permanently deletes an issue trigger. This action cannot be undone.

Disable an issue trigger

This endpoint disables an issue trigger so it stops producing issues.

Enable an issue trigger

This endpoint enables a previously disabled issue trigger.

Transformations

A transformation represents JavaScript code that will be executed on a connection's requests. Transformations are applied to connections using Rules.

Retrieve transformations

This endpoint lists transformations, or a subset of transformations.

Create a transformation

This endpoint creates a transformation.

Create/Update a transformation

This endpoint creates a transformation, or updates an existing transformation by name.

Get transformations count

Retrieve a transformation

This endpoint retrieves a specific transformation.

Update a transformation

This endpoint updates a transformation.

Delete a transformation

This endpoint permanently deletes a transformation. This action cannot be undone.

Test a transformation

This endpoint executes a transformation against a sample request payload and returns the transformed result without persisting anything.

Get transformation executions

Get a transformation execution

Notifications

Notifications let your team receive alerts anytime an issue changes.

Webhook Notifications

This endpoint enables or disables webhook notifications for the project, and sets the topics and source to deliver them to.

List all custom domains and their verification statuses for the project

Add a custom domain to the project

Removes a custom domain from the project

Requests

A request represent a webhook received by Hookdeck.

Retrieve requests

This endpoint lists requests, or a subset of requests.

Retrieve a request

This endpoint retrieves a specific request.

Get a request raw body data

Retry a request

This endpoint retries a specific request. Retrying a request creates new events based on the request for the specified connections (or all matching connections if none specified).

Replay a request

Replays a request through the full pipeline, creating a new request and new events. The original request and its events remain unchanged. Transformations, filters, and other pipeline rules are re-evaluated with the current configuration. By default, replays to all currently active connections on the request source — this also backfills traffic onto connections added after the original request was ingested. If the source has no active connections, the replay still creates a new request, rejected with cause NO_CONNECTION. Optionally specify source_id to target another source — alone it replays onto all of that source’s active connections, or combine it with webhook_ids to target specific connections on that source. webhook_ids without source_id may target any connections in the project; when they span multiple sources the replay fans out into one new request per target source.

Retrieve request events

This endpoint retrieves all events that were created as a result of the specified request.

Retrieve request ignored events

This endpoint retrieves all events that were ignored (filtered out) for the specified request.

Events

An event is any request that Hookdeck receives from a source.

Retrieve events

This endpoint lists events, or a subset of events.

Retrieve an event

This endpoint retrieves a specific event. The response contains the data object with the properties body and headers, representing the original data for that request.

Get a event raw body data

Retry an event

This endpoint retries a specific event. Retrying an event will cause a new attempt to be made to deliver it to the destination.

Replay an event

Replays an event by re-ingesting the original request through the full pipeline, creating a new request and new events. The original event remains unchanged. By default, replays to the same connection as the original event. Optionally specify one or more connections via webhook_ids — any connections in the project. When the target connections span multiple sources, the replay fans out into one new request per target source. Alternatively specify source_id to target another source — alone it replays onto all of that source’s active connections, or combine it with webhook_ids to target specific connections on that source.

Cancel an event

This endpoint cancels a pending event. Only events with a status of QUEUED, SCHEDULED, or HOLD can be cancelled.

Cancel an event

This endpoint cancels a pending event. Only events with a status of QUEUED, SCHEDULED, or HOLD can be cancelled.

Attempts

An attempt is any request that Hookdeck makes on behalf of an event.

Retrieve attempts

This endpoint lists attempts, or a subset of attempts.

Retrieve an attempt

This endpoint retrieves a specific attempt. When retrieving a completed attempt, the response will contain the body of the destination's response. If the body is not yet available in our backend service the body will be set to NOT_AVAILABLE_YET.

Bookmarks

A bookmark lets you conveniently store and replay a specific request.

Retrieve bookmarks

This endpoint lists bookmarks, or a subset of bookmarks.

Create a bookmark

This endpoint creates a bookmark from a specific event.

Retrieve a bookmark

This endpoint retrieves a specific bookmark.

Update a bookmark

This endpoint updates a bookmark.

Delete a bookmark

This endpoint permanently deletes a bookmark. This action cannot be undone.

Get a bookmark raw body data

Trigger a bookmark

This endpoint triggers a bookmark, replaying its associated event against all matching connections.

Issues

Issues lets you track problems in your project and communicate resolution steps with your team.

Retrieve issues

This endpoint lists issues, or a subset of issues.

Get the number of issues

Retrieve an issue

This endpoint retrieves a specific issue.

Update an issue

This endpoint updates an issue's status.

Dismiss an issue

This endpoint dismisses an issue.

Metrics

Query aggregated metrics for events, requests, and attempts with time-based grouping and filtering.

Query request metrics

Query aggregated request metrics with time-based grouping and filtering

Query event metrics

Query aggregated event metrics with time-based grouping and filtering

Query attempt metrics

Query aggregated attempt metrics with time-based grouping and filtering

Query event metrics grouped by individual issue

Returns metrics for events broken down by individual issue IDs. Uses arrayJoin to create one row per issue per event, enabling per-issue analytics. Useful for tracking which issues affect the most events over time.

Query queue depth metrics

Query queue depth metrics for destinations and delivery groups (pending events count and age)

Query transformation execution metrics

Query aggregated transformation execution metrics with time-based grouping and filtering

Query events pending timeseries metrics

Query aggregated events pending timeseries metrics with time-based grouping and filtering

Publish API

Authentication: The Publish API uses the same authentication as the Hookdeck REST API (Authorization: Bearer $API_KEY or Basic Auth). This is different from Source authentication - when sending directly to Source URLs, see Source Authentication.

The Hookdeck Publish API is a distinct endpoint to send requests to one of your Hookdeck sources, either by name or by ID. The Publish API is authenticated just like the rest of the Hookdeck API.

Requests sent via the Publish API are automatically considered verified and do not require additional verification. If your Source Type is set to Hookdeck Publish API (PUBLISH_API via API), only requests via the Publish API will be accepted. Regardless of the source type and authentication method, it's always possible to send requests via the Publish API for any given source.

The Publish API has its own specification and no rate limit.

The API URL is https://hkdk.events/v1/publish

Required headers

The following headers are required for all requests to the Publish API. Those reserved headers will be trimmed from the request once validated.

• Authorization: The value of this header is the Authorization header value from the request you wish to publish.
• Content-Type: The value of this header is the Content-Type header value from the request you wish to publish. Must be one of Hookdeck supported content types.

You must include one of the following headers:

• X-Hookdeck-Source-Id: The value of this header is the id of the source you wish to publish the request to.
• X-Hookdeck-Source-Name: The value of this header is the name of the source you wish to publish the request to.

Behavior

The Publish API does not have a specification beyond the required headers. The Publish API will accept any request valid for the Source it is published to, and the headers, body, path, and query params will be passed through as is.

Path

For example, if you POST to /v1/publish/orders, the path value will be /orders. This path will be forwarded to the destination endpoint unless the Hookdeck Destination has Path forwarding disabled.

Bulk retry events

Bulk retry operations allow you to retry many events at once. A bulk retry is first estimated, then created, then processed asynchronously.

Retrieve events bulk retries

This endpoint lists events bulk retries.

Create events bulk retry

This endpoint creates and starts an events bulk retry using the provided query.

Generate events bulk retry plan

This endpoint estimates the number of events matched by the provided query before creating a bulk retry. Use the plan to preview impact.

Retrieve events bulk retry

This endpoint retrieves a specific events bulk retry.

Cancel events bulk retry

This endpoint cancels a pending or in-progress events bulk retry.

Bulk cancel events

Bulk cancel operations allow you to cancel multiple pending events at once.

Retrieve events bulk cancels

This endpoint lists events bulk cancels.

Create events bulk cancel

This endpoint creates and starts an events bulk cancel using the provided query.

Generate events bulk cancel plan

This endpoint estimates the number of events matched by the provided query before creating a bulk cancel.

Retrieve events bulk cancel

This endpoint retrieves a specific events bulk cancel.

Bulk retry ignored events

Bulk retry ignored events allow you to retry many events that were previously ignored (for instance due to filter rules) at once.

Retrieve ignored events bulk retries

This endpoint lists ignored events bulk retries.

Create ignored events bulk retry

This endpoint creates and starts an ignored events bulk retry using the provided query.

Generate ignored events bulk retry plan

This endpoint estimates the number of ignored events matched by the provided query before creating a bulk retry.

Retrieve ignored events bulk retry

This endpoint retrieves a specific ignored events bulk retry.

Cancel ignored events bulk retry

This endpoint cancels a pending or in-progress ignored events bulk retry.

Bulk retry requests

Bulk retry requests allow you to re-ingest many previously received requests at once.

Retrieve requests bulk retries

This endpoint lists requests bulk retries.

Create requests bulk retry

This endpoint creates and starts a requests bulk retry using the provided query.

Generate requests bulk retry plan

This endpoint estimates the number of requests matched by the provided query before creating a bulk retry.

Retrieve requests bulk retry

This endpoint retrieves a specific requests bulk retry.

Cancel requests bulk retry

This endpoint cancels a pending or in-progress requests bulk retry.

Bulk replay requests

Bulk replay requests re-runs the full pipeline for many historical requests through a chosen set of target connections. Useful for backfilling new connections and for reprocessing after a transformation change.

Retrieve requests bulk replays

This endpoint lists requests bulk replays.

Create requests bulk replay

Creates and starts a requests bulk replay. The query.target object selects where to replay: source_id targets a source — alone it replays onto all of the source’s active connections (resolved as the replay runs), or combine it with webhook_ids to target specific connections on that source. The remaining query fields filter which historical requests to replay.

Generate requests bulk replay plan

Estimates the number of requests matched by the provided filter before creating a bulk replay. Pass the same query payload that you will POST to create the bulk replay — except query.target, which is not a filter and may be omitted.

Retrieve requests bulk replay

This endpoint retrieves a specific requests bulk replay.

Cancel requests bulk replay

This endpoint cancels a pending or in-progress requests bulk replay.

Retry

The retry rule determines the rate and limit of automatic retries on failed events.

Delay

The delay rule allows you to introduce a delay between the moment Hookdeck receives an event, and when it's forwarded to your destination.

The maximum delay is 24 hours (86,400,000 milliseconds).

Filter

The filter rule allows you to permit and route events conditionally based on the contents of their Headers, Body, Query, and/or Path.

For more information on how to set up filters, including syntax, review our filter documentation.

Transform

The transform rule allows you to run arbitrary JavaScript to transform the event data.

For more information on how to use transformations, check the transformation documentation.

Deduplicate

The deduplication rule allows you to ignore redundant events by comparing them against previously processed events within a time window. You control what makes events "identical" - from exact payload matching to comparing only specific fields that matter to your use case.

For more information on how to use deduplication, check the deduplication documentation.

Not specifying any of include_fields or exclude_fields will deduplicate the full payload. Fields specified must start with body, headers, query or path.