A request is any HTTP request that Hookdeck receives from a source.


When Hookdeck receives a request from a source, it attempts to create an event for each associated connection. There are a few exceptions to this process, listed below.

Ignored events

If an event is not created for a given connection, for example, because it doesn't pass a filter rule, an ignored event is recorded instead.

Ignored event causes

ARCHIVEDThe associated connection is archived
FILTEREDThe associated connection's filtering rule did not pass
TRANSFORMATION_FAILEDThe associated connection's transformation rule failed to execute and resulted in a FATAL error
CLI_DISCONNECTEDThe associated connection is a CLI ONLY connection but no CLI client was connected when the request was received

Rejected requests

A request is marked as rejected if a condition for creating events is not met – for example, if the source is archived.

Rejection causes

SOURCE_ARCHIVEDThe associated source with the request URL is archived
VERIFICATION_FAILEDA verification integration configured for the request source identified invalid credentials or signature
NO_WEBHOOKThere are no connections associated with the request source
UNSUPPORTED_HTTP_METHODThe request HTTP method is not supported.
UNSUPPORTED_CONTENT_TYPEThe request content-type is not supported
UNPARSABLE_JSONThe request content-type is JSON but the body is unparsable
PAYLOAD_TOO_LARGEThe request payload was larger then what's allowed for your current quota
UNKNOWNAn unknown error occur, the team is investigating

Retrying a request

Rejected requests can be retried. Hookdeck re-runs the processing logic for the request according to the new result and creates the associated events.

No events will be created for connections that did not exist at the time of original receipt. If new connections have since been added to the source, they will be ignored upon retrying the request.

Additionally, specific ignored events can be retried individually.

Requests eligible for retries

Only rejected requests are eligible for retry. Additionally, you cannot retry requests that have been rejected for the following reasons because they will be rejected again:


Request bulk retries

Rejected requests can be bulk retried from the requests page. The bulk retry dropdown will automatically exclude requests that are not eligible for retry. Bulk retries are done asynchronously and may take some time to complete, a progress bar will be displayed once the retry is submitted.

The bulk retry speed is throttled based on the your workspace max attempts per second quota. Increase the quota will also increase the speed of the bulk retry.

View requests

Hookdeck allows you to browse a historical record of all requests within your retention period, or to filter requests by property. This log is useful for debugging and troubleshooting requests, as well as the events they generate.

Browse all requests

The Requests link in the dashboard's sidebar takes you to the Requests page, where you can view requests in descending order.

The request list displays up to 100 requests at a time. Travel back and forth using the Previous and Next buttons at the bottom of the list.

GET /requests

Browse filtered requests

Beneath the Requests link, you can find any custom request views, including Hookdeck's default views: Accepted and Rejected.

Filter requests

If your desired filters are not already saved as a filtered view, you can still use the Requests page to find the requests you're looking for.

  1. Open the Requests page to see a list of all requests, in descending order.
  2. Select any properties you'd like to filter on.
GET /requests

To filter the list of requests, use only supported operators.

For example, append ?created_at[gte]=2021-10-12&created_at[lte]=2021-10-13 to retrieve requests for that specific 24-hour period.

Requests past your workspace archival window are not returned

Filterable properties

StatusThe accepted or rejected status of the request
SourcesAny source within Hookdeck
DateA specific date or interval
Rejection CauseThe cause for which the request was rejected
RequestA partial JSON match of the request headers, body, or query; or a partial string match of the request path
Ignored EventsThe count of events that were ignored for the request
RequestThe count of events that were created for the request

The rejection cause and status filters can conflict; in the case where the status is Accepted and a Rejection Cause is set, the status takes precedence.

Inspect a request

Inspecting a request reveals the associated request data, which can be used to understand the flow of events through your system and to troubleshoot issues.

  1. Locate the request you wish to inspect.
  2. For a summary of its associated data, click the request. Its details will display in the right-hand sidebar.
  3. You can expand the metadata and headers section in the right-hand sidebar to see more information.
GET /requests/:id

For each request, the initial request's headers, path, body, and query are provided either as plain text or JSON. Additionally, a list of events and ignored events resulting from that request will be displayed below the request.

Request and event data

A request's associated events (including ignored events) store data. You can see this date in the right-hand sidebar when you select a request and an event. You can use this data to filter and sort events, and track and resolve issues.

The displayed events depend on the current workspace view. Only CLI events will display in the CLI view and vice versa.

Request properties

HeadersEvery header contained in the initial request (does not include Hookdeck's headers)
PathThe complete path of the initial request
QueryEvery query included in the URL of the initial request
BodyThe initial request's payload (boolean, string, number, JSON, or null)

Event properties

Each event contains properties that can help you track and resolve issues.

StatusThe cause for which the event was ignored
IDThe event ID
ConnectionThe associated connection of the ignored event

Ignored event properties

CauseThe cause for which the event was ignored
ConnectionThe associated connection of the ignored event

Custom request views

Using custom request views allows you to preserve a filtered view of your requests for future access.

Create a custom view

  1. Open the Requests page.
  2. Make sure Recent Filters is expanded.
  3. When the desired filters are set, the results will automatically update.
  4. Once satisfied with your filters, click Save View .
  5. Name your view and click Save .

Once saved, custom views are accessible in your dashboard's sidebar.

Update filters on a custom view

  1. Select the custom view in your dashboard's sidebar.
  2. Make sure Recent Filters is expanded.
  3. When the desired filters are set, the results will automatically update.
  4. Once satisfied with your filters, click Save View .

Rename a custom view

  1. Select the custom view in your dashboard's sidebar.
  2. Open the dropdown next to the custom view name at the top of the page, and select Rename.
  3. Give your custom view a new name and click Update .