List, retrieve, retry, mute, and inspect events and their delivery attempts. An event is any request Hookdeck received from a source; an attempt is each delivery try against a destination, including status, response body, response time, and error code.
openapi: 3.0.1
info:
title: Hookdeck Events API
version: 1.0.0
description: List, retrieve, retry, mute, and inspect events and their delivery attempts. An event is any request Hookdeck
received from a source; an attempt is each delivery try against a destination.
contact:
name: Hookdeck Support
url: https://hookdeck.com/contact-us
email: info@hookdeck.com
servers:
- url: https://api.hookdeck.com/2025-07-01
description: Production API
security:
- bearerAuth: []
- basicAuth: []
tags:
- name: Events
description: An event is any request that Hookdeck receives from a source.
- name: Attempts
description: An attempt is any request that Hookdeck makes on behalf of an event.
paths:
/attempts:
get:
operationId: getAttempts
summary: Retrieve attempts
description: This endpoint lists attempts, or a subset of attempts.
tags:
- Attempts
responses:
'200':
description: List of attempts
content:
application/json:
schema:
$ref: '#/components/schemas/EventAttemptPaginatedResult'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/APIErrorResponse'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/APIErrorResponse'
parameters:
- in: query
name: id
schema:
anyOf:
- type: string
maxLength: 255
description: Attempt ID
- type: array
items:
type: string
maxLength: 255
description: Attempt ID
description: ID of the attempt
- in: query
name: event_id
schema:
anyOf:
- type: string
maxLength: 255
description: Event ID
- type: array
items:
type: string
maxLength: 255
description: Event ID
description: Event the attempt is associated with
- in: query
name: order_by
schema:
anyOf:
- type: string
maxLength: 255
enum:
- created_at
- type: array
items:
type: string
maxLength: 255
enum:
- created_at
minItems: 2
maxItems: 2
description: Sort key(s)
- in: query
name: dir
schema:
anyOf:
- type: string
enum:
- asc
- desc
- type: array
items:
type: string
enum:
- asc
- desc
minItems: 2
maxItems: 2
description: Sort direction(s)
- in: query
name: limit
schema:
type: integer
minimum: 0
maximum: 255
description: Result set size
- in: query
name: next
schema:
type: string
maxLength: 255
description: The ID to provide in the query to get the next set of results
- in: query
name: prev
schema:
type: string
maxLength: 255
description: The ID to provide in the query to get the previous set of results
/attempts/{id}:
get:
operationId: getAttempt
summary: Retrieve an attempt
description: 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`.
tags:
- Attempts
responses:
'200':
description: A single attempt
content:
application/json:
schema:
$ref: '#/components/schemas/EventAttempt'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/APIErrorResponse'
parameters:
- in: path
name: id
schema:
type: string
description: Attempt ID
required: true
/events:
get:
operationId: getEvents
summary: Retrieve events
description: This endpoint lists events, or a subset of events.
tags:
- Events
responses:
'200':
description: List of events
content:
application/json:
schema:
$ref: '#/components/schemas/EventPaginatedResult'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/APIErrorResponse'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/APIErrorResponse'
parameters:
- in: query
name: id
schema:
anyOf:
- type: string
maxLength: 255
description: Event ID
- type: array
items:
type: string
maxLength: 255
description: Event ID
description: Filter by event IDs
- in: query
name: status
schema:
anyOf:
- $ref: '#/components/schemas/EventStatus'
- type: array
items:
$ref: '#/components/schemas/EventStatus'
description: Lifecyle status of the event
- in: query
name: webhook_id
schema:
anyOf:
- type: string
maxLength: 255
description: Connection (webhook) ID
- type: array
items:
type: string
maxLength: 255
description: Connection (webhook) ID
description: Filter by connection (webhook) IDs
- in: query
name: destination_id
schema:
anyOf:
- type: string
maxLength: 255
description: Destination ID
- type: array
items:
type: string
maxLength: 255
description: Destination ID
description: Filter by destination IDs
- in: query
name: source_id
schema:
anyOf:
- type: string
maxLength: 255
description: Source ID
- type: array
items:
type: string
maxLength: 255
description: Source ID
description: Filter by source IDs
- in: query
name: attempts
schema:
anyOf:
- type: integer
minimum: 0
- $ref: '#/components/schemas/Operators'
description: Filter by number of attempts
- in: query
name: response_status
schema:
anyOf:
- type: integer
minimum: 200
maximum: 600
- $ref: '#/components/schemas/Operators'
- type: array
items:
type: integer
minimum: 200
maximum: 600
nullable: true
description: Filter by HTTP response status code
- in: query
name: successful_at
schema:
anyOf:
- type: string
format: date-time
- $ref: '#/components/schemas/Operators'
nullable: true
description: Filter by `successful_at` date using a date operator
- in: query
name: created_at
schema:
anyOf:
- type: string
format: date-time
- $ref: '#/components/schemas/Operators'
description: Filter by `created_at` date using a date operator
- in: query
name: error_code
schema:
anyOf:
- $ref: '#/components/schemas/AttemptErrorCodes'
- type: array
items:
$ref: '#/components/schemas/AttemptErrorCodes'
description: Filter by error code code
- in: query
name: cli_id
schema:
anyOf:
- type: string
- type: object
properties:
any:
type: boolean
all:
type: boolean
additionalProperties: false
- type: array
items:
type: string
nullable: true
description: Filter by CLI IDs. `?[any]=true` operator for any CLI.
- in: query
name: last_attempt_at
schema:
anyOf:
- type: string
format: date-time
- $ref: '#/components/schemas/Operators'
nullable: true
description: Filter by `last_attempt_at` date using a date operator
- in: query
name: next_attempt_at
schema:
anyOf:
- type: string
format: date-time
- $ref: '#/components/schemas/Operators'
nullable: true
description: Filter by `next_attempt_at` date using a date operator
- in: query
name: search_term
schema:
type: string
minLength: 3
description: URL Encoded string of the value to match partially to the body, headers, parsed_query or path
- in: query
name: headers
schema:
anyOf:
- type: string
- type: object
properties: {}
additionalProperties: false
description: URL Encoded string of the JSON to match to the data headers
x-docs-force-simple-type: true
x-docs-type: JSON
- in: query
name: body
schema:
anyOf:
- type: string
- type: object
properties: {}
additionalProperties: false
description: URL Encoded string of the JSON to match to the data body
x-docs-force-simple-type: true
x-docs-type: JSON
- in: query
name: parsed_query
schema:
anyOf:
- type: string
- type: object
properties: {}
additionalProperties: false
description: URL Encoded string of the JSON to match to the parsed query (JSON representation of the query)
x-docs-force-simple-type: true
x-docs-type: JSON
- in: query
name: path
schema:
type: string
description: URL Encoded string of the value to match partially to the path
- in: query
name: cli_user_id
schema:
anyOf:
- type: string
- type: array
items:
type: string
nullable: true
x-docs-hide: true
- in: query
name: issue_id
schema:
anyOf:
- type: string
maxLength: 255
- type: array
items:
type: string
maxLength: 255
x-docs-hide: true
- in: query
name: event_data_id
schema:
anyOf:
- type: string
maxLength: 255
- type: array
items:
type: string
maxLength: 255
x-docs-hide: true
- in: query
name: bulk_retry_id
schema:
anyOf:
- type: string
maxLength: 255
- type: array
items:
type: string
maxLength: 255
x-docs-hide: true
- in: query
name: include
schema:
type: string
enum:
- data
description: Include the data object in the event model
x-docs-hide: true
- in: query
name: progressive
schema:
type: string
enum:
- 'true'
- 'false'
description: Enable progressive loading for partial results
x-docs-hide: true
- in: query
name: order_by
schema:
type: string
maxLength: 255
enum:
- created_at
description: Sort key
- in: query
name: dir
schema:
type: string
enum:
- asc
- desc
description: Sort direction
- in: query
name: limit
schema:
type: integer
minimum: 0
maximum: 255
description: Result set size
- in: query
name: next
schema:
type: string
maxLength: 255
description: The ID to provide in the query to get the next set of results
- in: query
name: prev
schema:
type: string
maxLength: 255
description: The ID to provide in the query to get the previous set of results
/events/{id}:
get:
operationId: getEvent
summary: Retrieve an event
description: 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.
tags:
- Events
responses:
'200':
description: A single event
content:
application/json:
schema:
$ref: '#/components/schemas/Event'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/APIErrorResponse'
parameters:
- in: path
name: id
schema:
type: string
description: Event ID
required: true
/events/{id}/raw_body:
get:
operationId: getEventRawBody
summary: Get a event raw body data
description: ''
tags:
- Events
responses:
'200':
description: A request raw body data
content:
application/json:
schema:
$ref: '#/components/schemas/RawBody'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/APIErrorResponse'
parameters:
- in: path
name: id
schema:
type: string
description: Event ID
required: true
/events/{id}/retry:
post:
operationId: retryEvent
summary: Retry an event
description: This endpoint retries a specific event. Retrying an event will cause a new attempt to be made to deliver
it to the destination.
tags:
- Events
responses:
'200':
description: Retried event with event attempt
content:
application/json:
schema:
$ref: '#/components/schemas/RetriedEvent'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/APIErrorResponse'
parameters:
- in: path
name: id
schema:
type: string
description: Event ID
required: true
/events/{id}/cancel:
put:
operationId: cancelEvent
summary: Cancel an event
description: This endpoint cancels a pending event. Only events with a status of `QUEUED`, `SCHEDULED`, or `HOLD` can
be cancelled.
tags:
- Events
responses:
'200':
description: A cancelled event
content:
application/json:
schema:
$ref: '#/components/schemas/Event'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/APIErrorResponse'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/APIErrorResponse'
parameters:
- in: path
name: id
schema:
type: string
description: Event ID
required: true
/events/{id}/mute:
put:
operationId: cancelEvent_mute
summary: Cancel an event
description: This endpoint cancels a pending event. Only events with a status of `QUEUED`, `SCHEDULED`, or `HOLD` can
be cancelled.
tags:
- Events
responses:
'200':
description: A cancelled event
content:
application/json:
schema:
$ref: '#/components/schemas/Event'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/APIErrorResponse'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/APIErrorResponse'
parameters:
- in: path
name: id
schema:
type: string
description: Event ID
required: true
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
basicAuth:
type: http
scheme: basic
schemas:
AttemptStatus:
type: string
enum:
- FAILED
- SUCCESSFUL
description: Attempt status
RetriedEvent:
type: object
properties:
id:
type: string
description: ID of the event
team_id:
type: string
description: ID of the project
webhook_id:
type: string
description: ID of the associated connection (webhook)
source_id:
type: string
description: ID of the associated source
destination_id:
type: string
description: ID of the associated destination
event_data_id:
type: string
description: ID of the event data
request_id:
type: string
description: ID of the request that created the event
attempts:
type: integer
description: Number of delivery attempts made
last_attempt_at:
type: string
format: date-time
nullable: true
description: Date of the most recently attempted retry
next_attempt_at:
type: string
format: date-time
nullable: true
description: Date of the next scheduled retry
response_status:
type: integer
nullable: true
description: Event status
error_code:
$ref: '#/components/schemas/AttemptErrorCodes'
status:
$ref: '#/components/schemas/EventStatus'
successful_at:
type: string
format: date-time
nullable: true
description: Date of the latest successful attempt
cli_id:
type: string
nullable: true
description: ID of the CLI the event is sent to
updated_at:
type: string
format: date-time
description: Date the event was last updated
created_at:
type: string
format: date-time
description: Date the event was created
data:
$ref: '#/components/schemas/EventData'
required:
- id
- team_id
- webhook_id
- source_id
- destination_id
- event_data_id
- request_id
- attempts
- last_attempt_at
- next_attempt_at
- status
- successful_at
- cli_id
- updated_at
- created_at
additionalProperties: false
OrderByDirection:
anyOf:
- enum:
- asc
- enum:
- desc
- enum:
- ASC
- enum:
- DESC
Operators:
type: object
properties:
gt:
type: string
format: date-time
nullable: true
gte:
type: string
format: date-time
nullable: true
le:
type: string
format: date-time
nullable: true
lte:
type: string
format: date-time
nullable: true
any:
type: boolean
all:
type: boolean
additionalProperties: false
SeekPagination:
type: object
properties:
order_by:
anyOf:
- type: string
- type: array
items:
type: string
dir:
anyOf:
- $ref: '#/components/schemas/OrderByDirection'
- type: array
items:
$ref: '#/components/schemas/OrderByDirection'
limit:
type: integer
prev:
type: string
next:
type: string
additionalProperties: false
EventAttemptPaginatedResult:
type: object
properties:
pagination:
$ref: '#/components/schemas/SeekPagination'
count:
type: integer
models:
type: array
items:
$ref: '#/components/schemas/EventAttempt'
additionalProperties: false
EventData:
type: object
properties:
url:
type: string
method:
type: string
path:
type: string
nullable: true
description: Raw path string
query:
type: string
nullable: true
description: Raw query param string
parsed_query:
anyOf:
- type: string
nullable: true
- type: object
properties: {}
nullable: true
description: JSON representation of query params
headers:
anyOf:
- type: string
- type: object
properties: {}
additionalProperties:
type: string
nullable: true
nullable: true
description: JSON representation of the headers
appended_headers:
type: array
items:
type: string
description: List of headers that were added by Hookdeck
body:
anyOf:
- type: string
- type: object
properties: {}
- type: array
items: {}
nullable: true
description: JSON or string representation of the body
is_large_payload:
type: boolean
description: Whether the payload is considered large payload and not searchable
required:
- url
- method
- path
- query
- parsed_query
- headers
- body
additionalProperties: false
nullable: true
description: Event data if included
Event:
type: object
properties:
id:
type: string
description: ID of the event
team_id:
type: string
description: ID of the project
webhook_id:
type: string
description: ID of the associated connection (webhook)
source_id:
type: string
description: ID of the associated source
destination_id:
type: string
description: ID of the associated destination
event_data_id:
type: string
description: ID of the event data
request_id:
type: string
description: ID of the request that created the event
attempts:
type: integer
description: Number of delivery attempts made
last_attempt_at:
type: string
format: date-time
nullable: true
description: Date of the most recently attempted retry
next_attempt_at:
type: string
format: date-time
nullable: true
description: Date of the next scheduled retry
response_status:
type: integer
nullable: true
description: Event status
error_code:
$ref: '#/components/schemas/AttemptErrorCodes'
status:
$ref: '#/components/schemas/EventStatus'
successful_at:
type: string
format: date-time
nullable: true
description: Date of the latest successful attempt
cli_id:
type: string
nullable: true
description: ID of the CLI the event is sent to
updated_at:
type: string
format: date-time
description: Date the event was last updated
created_at:
type: string
format: date-time
description: Date the event was created
data:
$ref: '#/components/schemas/EventData'
required:
- id
- team_id
- webhook_id
- source_id
- destination_id
- event_data_id
- request_id
- attempts
- last_attempt_at
- next_attempt_at
- status
- successful_at
- cli_id
- updated_at
- created_at
additionalProperties: false
AttemptErrorCodes:
type: string
enum:
- BAD_RESPONSE
- CANCELLED
- TIMEOUT
- NOT_FOUND
- CANCELLED_PAST_RETENTION
- CONNECTION_REFUSED
- CONNECTION_RESET
- MISSING_URL
- CLI
- CLI_UNAVAILABLE
- SELF_SIGNED_CERT
- ERR_TLS_CERT_ALTNAME_INVALID
- ERR_SSL_WRONG_VERSION_NUMBER
- NETWORK_ERROR
- NETWORK_REQUEST_CANCELED
- NETWORK_UNREACHABLE
- TOO_MANY_REDIRECTS
- INVALID_CHARACTER
- INVALID_URL
- SSL_ERROR_CA_UNKNOWN
- DATA_ARCHIVED
- SSL_CERT_EXPIRED
- BULK_RETRY_CANCELLED
- DNS_LOOKUP_FAILED
- HOST_UNREACHABLE
- INTERNAL_ERROR
- PROTOCOL_ERROR
- PAYLOAD_MISSING
- UNABLE_TO_GET_ISSUER_CERT
- SOCKET_CLOSED
- OAUTH2_HANDSHAKE_FAILED
- Z_DATA_ERROR
- UNKNOWN
description: Error code of the delivery attempt
AttemptTrigger:
type: string
enum:
- INITIAL
- MANUAL
- BULK_RETRY
- UNPAUSE
- AUTOMATIC
nullable: true
description: How the attempt was triggered
EventStatus:
type: string
enum:
- SCHEDULED
- QUEUED
- HOLD
- SUCCESSFUL
- FAILED
- CANCELLED
EventAttempt:
type: object
properties:
id:
type: string
description: Attempt ID
team_id:
type: string
description: ID of the project
event_id:
type: string
description: Event ID
destination_id:
type: string
description: Destination ID
response_status:
type: integer
nullable: true
description: Attempt's HTTP response code
attempt_number:
type: integer
nullable: true
description: Sequential number of attempts (up to and including this one) made for the associated event
trigger:
$ref: '#/components/schemas/AttemptTrigger'
error_code:
$ref: '#/components/schemas/AttemptErrorCodes'
body:
anyOf:
- type: object
properties: {}
nullable: true
description: Response body from the destination
- type: string
nullable: true
description: Response body from the destination
requested_url:
type: string
nullable: true
description: URL of the destination where delivery was attempted
http_method:
type: string
enum:
- GET
- POST
- PUT
- PATCH
- DELETE
nullable: true
description: HTTP method used to deliver the attempt
bulk_retry_id:
type: string
nullable: true
description: ID of associated bulk retry
status:
$ref: '#/components/schemas/AttemptStatus'
successful_at:
type: string
format: date-time
nullable: true
description: Date the attempt was successful
delivered_at:
type: string
format: date-time
nullable: true
description: Date the attempt was delivered
responded_at:
type: string
format: date-time
nullable: true
description: Date the destination responded to this attempt
delivery_latency:
type: integer
nullable: true
description: Time elapsed between attempt initiation and final delivery (in ms)
response_latency:
type: integer
nullable: true
description: Time elapsed between attempt initiation and a response from the destination (in ms)
updated_at:
type: string
format: date-time
description: Date the attempt was last updated
created_at:
type: string
format: date-time
description: Date the attempt was created
required:
- id
- team_id
- event_id
- destination_id
- status
- updated_at
- created_at
additionalProperties: false
nullable: true
APIErrorResponse:
type: object
properties:
code:
type: string
description: Error code
status:
type: number
format: float
description: Status code
message:
type: string
description: Error description
data:
type: object
properties: {}
nullable: true
required:
- code
- status
- message
additionalProperties: false
description: Error response model
EventPaginatedResult:
type: object
properties:
pagination:
$ref: '#/components/schemas/SeekPagination'
count:
type: integer
models:
type: array
items:
$ref: '#/components/schemas/Event'
additionalProperties: false
RawBody:
type: object
properties:
body:
type: string
required:
- body
additionalProperties: false