Events & Attempts

An event is any outgoing request that Hookdeck queues based on a request, whereas an attempt is a specific delivery effort that Hookdeck makes for an event.

Events

Events are limited to 50 automatic retries, but can be manually retried as many times as you like.

When receiving a request from a source with multiple connections, Hookdeck creates a separate event for each connection.

View events

Hookdeck allows you to browse a historical record of all events, or to filter and sort events by property.

Browse all events

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

The event list displays up to 100 events at a time. Travel back and forth using the buttons at the bottom of the list.

GET /events

Browse filtered events

Beneath the Events link, you can find any custom event views, including Hookdeck's default views: Successful, Failed, Pending, and Paused.

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

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

Filter and sort events

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

  1. Open the Events page to see a list of all events, in descending order.
  2. Select any properties you'd like to filter on.
  3. To sort events, click the header of the first column and select your desired sort property.

Filterable properties

PropertyDescription
StatusAny event status in Hookdeck
ConnectionAny connection within Hookdeck
SourcesAny source within Hookdeck
DestinationsAny destination within Hookdeck
DateA specific date or interval
HTTP ResponseAn HTTP status code, an interval of codes, or any Hookdeck error codes
RequestA partial JSON match of the request headers, body, or query; or a partial string match of the request path
AttemptsThe count of attempts made

Filtering the request property is not supported for payloads exceeding 2.5 MB. The histogram and total count are disabled when filtering or request

Sortable properties

PropertyDescription
Event DateThe date the event was received by Hookdeck
Last Attempt AtThe date the most recent delivery attempt was made

Inspect an event

Inspecting an event reveals the associated event data, which can be used to understand the flow of requests through your system and to troubleshoot issues.

When selecting an event, the most recent attempt is used to populate the response data. Select any of the other attempts to view their specific response data.

  1. Locate the event you wish to inspect.
  2. For a summary of its associated data, click the event. Its details will be displayed in the right-hand sidebar.
  3. You can expand and collapse sections in the right-hand sidebar to view more or less information.
GET /events/:id

For each event, the initial request's headers, path, body, and query are provided either as plain text or JSON. Similarly, each attempt's response is provided as plain text or JSON.

Event & attempt data

Events and requests store associated data that let you filter and sort events, and track and resolve issues.

Event data

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

PropertyDescription
StatusThe event's status
Event DateThe date the event was received by Hookdeck
AttemptsThe number of times Hookdeck has attempted to deliver the event
ConnectionThe associated connection
Next Attempt AtThe date the next automatic delivery attempt will be made

Attempt properties

PropertyDescription
StatusThe attempt's status
Attempt DateThe date Hookdeck attempted to deliver the event to the destination
Attempt NumberThe number of times Hookdeck has attempted to deliver the event (up to and including this attempt)
Attempt ResponseThe body of the destination server's response, including HTTP status

Custom event views

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

Create a custom view

  1. Open the Events page.
  2. Make sure the filters section 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 the filters section 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 .

Status and error codes

Below is a reference of Hookdeck's internal event statuses and error codes, as well as some common HTTP status codes.

Hookdeck event status

Event StatusDescription
PendingThe event is pending delivery
FailedThe most recent delivery attempt received an HTTP status code in the failure range
SuccessfulThe most recent delivery attempt received an HTTP status code in the success range
On holdDelivery will be attempted when the associated connection is unpaused

Hookdeck error codes

If your destination is unreachable or fails to respond, the event will appear in the dashboard with an ERR flag. A more specific error code can be found by inspecting the event.

Hookdeck Error CodeExplanation
CONNECTION_REFUSEDThe request to your destination could not be made because the connection was refused.
CONNECTION_RESETThe request to your destination could not be made because the connection was forcibly closed by your server.
NOT_FOUNDThe request to your destination could not be made because the domain or host was not found or unavailable.
TIMEOUTThe request to your destination exceeded the 60-second timeout window. The request might have still been processed by your destination.
MISSING_URLYour destination does not have a HTTP URL configured. It can only receive attempts on the CLI.
CLIThe attempt failed to be forwarded to your local server by the CLI. Check your console for more details.
SELF_SIGNED_CERTYour destination uses a self-signed SSL certificate. Hookdeck only supports valid, verifiable certificates.
ERR_TLS_CERT_ALTNAME_INVALIDYour destination's SSL certificate is not valid.
SSL_CERT_EXPIREDYour destination's SSL certificate is expired.
SSL_ERROR_CA_UNKNOWNThe intermediate certificate / CA Bundle is invalid or mismatched.
UNKNOWNAn uncategorized error occurred. If one of these errors is triggered, Hookdeck's technical team is notified and will investigate.
SOCKET_CLOSEDUsually caused by the destination endpoint being unreachable by Hookdeck. Ensure that the endpoint is publicly available on the Internet.

HTTP response status codes

When your destination responds with a valid HTTP response code, it will be displayed as the event's status. A response code between 200 and 299 is considered successful. A response code of 400 or above is considered a failure.

Status CodeDescriptionExplanation
200Good RequestYour request is valid.
400Bad RequestYour request is invalid and could not be understood.
401UnauthorizedYour API key is wrong.
403ForbiddenAccess to the requested resource is restricted.
404Not FoundThe resource could not be found.
413Payload Too LargeThe payload size exceeds the limit.
422Unprocessable EntryThe request was understood but contains invalid input.
429Too Many RequestsThe request limit for a specific time period has been exceeded.
500Internal Server ErrorThere was a problem with the server. Try again later.
503Service UnavailableThe server is temporarily offline for maintenance. Try again later.