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