Hookdeck
Hookdeck Bulk Operations API

Plan, schedule, and cancel bulk operations that retry or cancel many events, requests, or ignored events at once. Each bulk operation reports per-batch counts, total scope, and live progress, and can be cancelled mid-run.
Hookdeck Bulk Operations API is one of 12 APIs that Hookdeck publishes on the APIs.io network, described by a machine-readable OpenAPI specification.
This API exposes 5 machine-runnable capabilities that can be deployed as REST, MCP, or Agent Skill surfaces via Naftiko.
Tagged areas include Bulk Operations, Webhooks, and Event Gateways. The published artifact set on APIs.io includes API documentation, an OpenAPI specification, and 5 Naftiko capability specs.
Documentation GitHub OpenAPI
OpenAPI Specification

openapi: 3.0.1
info:
  title: Hookdeck Bulk Operations API
  version: 1.0.0
  description: Plan, schedule, and cancel bulk operations that retry or cancel many events, requests, or ignored events at
    once. Returns progress and per-batch counts.
  contact:
    name: Hookdeck Support
    url: https://hookdeck.com/contact-us
    email: [email protected]
servers:
- url: https://api.hookdeck.com/2025-07-01
  description: Production API
security:
- bearerAuth: []
- basicAuth: []
tags:
- name: Bulk cancel events
  description: Bulk cancel operations allow you to cancel multiple pending events at once.
- name: Bulk retry events
  description: Bulk retry operations allow you to retry many events at once. A bulk retry is first estimated, then created,
    then processed asynchronously.
- name: Bulk retry ignored events
  description: Bulk retry ignored events allow you to retry many events that were previously ignored (for instance due to
    filter rules) at once.
- name: Bulk retry requests
  description: Bulk retry requests allow you to re-ingest many previously received requests at once.
paths:
  /bulk/events/cancel:
    get:
      operationId: getEventBulkCancels
      summary: Retrieve events bulk cancels
      description: This endpoint lists events bulk cancels.
      tags:
      - Bulk cancel events
      responses:
        '200':
          description: List of events bulk cancels
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchOperationPaginatedResult'
        '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: cancelled_at
        schema:
          anyOf:
          - type: string
            format: date-time
            nullable: true
          - $ref: '#/components/schemas/Operators'
          description: Filter by date the bulk cancel was cancelled
      - in: query
        name: completed_at
        schema:
          anyOf:
          - type: string
            format: date-time
            nullable: true
          - $ref: '#/components/schemas/Operators'
          description: Filter by date the bulk cancel completed
      - in: query
        name: created_at
        schema:
          anyOf:
          - type: string
            format: date-time
            nullable: true
          - $ref: '#/components/schemas/Operators'
          description: Filter by date the bulk cancel was created
      - in: query
        name: id
        schema:
          anyOf:
          - type: string
            maxLength: 255
            description: Bulk cancel ID
          - type: array
            items:
              type: string
              maxLength: 255
              description: Bulk cancel ID
          description: Filter by bulk cancel IDs
      - in: query
        name: query
        schema:
          type: object
          properties:
            id:
              anyOf:
              - type: string
                maxLength: 255
                description: Event ID
              - type: array
                items:
                  type: string
                  maxLength: 255
                  description: Event ID
              description: Filter by event IDs
            status:
              anyOf:
              - $ref: '#/components/schemas/EventStatus'
              - type: array
                items:
                  $ref: '#/components/schemas/EventStatus'
              description: Lifecyle status of the event
            webhook_id:
              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
            destination_id:
              anyOf:
              - type: string
                maxLength: 255
                description: Destination ID
              - type: array
                items:
                  type: string
                  maxLength: 255
                  description: Destination ID
              description: Filter by destination IDs
            source_id:
              anyOf:
              - type: string
                maxLength: 255
                description: Source ID
              - type: array
                items:
                  type: string
                  maxLength: 255
                  description: Source ID
              description: Filter by source IDs
            attempts:
              anyOf:
              - type: integer
                minimum: 0
              - $ref: '#/components/schemas/Operators'
              description: Filter by number of attempts
            response_status:
              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
            successful_at:
              anyOf:
              - type: string
                format: date-time
              - $ref: '#/components/schemas/Operators'
              nullable: true
              description: Filter by `successful_at` date using a date operator
            created_at:
              anyOf:
              - type: string
                format: date-time
              - $ref: '#/components/schemas/Operators'
              description: Filter by `created_at` date using a date operator
            error_code:
              anyOf:
              - $ref: '#/components/schemas/AttemptErrorCodes'
              - type: array
                items:
                  $ref: '#/components/schemas/AttemptErrorCodes'
              description: Filter by error code code
            cli_id:
              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.
            last_attempt_at:
              anyOf:
              - type: string
                format: date-time
              - $ref: '#/components/schemas/Operators'
              nullable: true
              description: Filter by `last_attempt_at` date using a date operator
            next_attempt_at:
              anyOf:
              - type: string
                format: date-time
              - $ref: '#/components/schemas/Operators'
              nullable: true
              description: Filter by `next_attempt_at` date using a date operator
            search_term:
              type: string
              minLength: 3
              description: URL Encoded string of the value to match partially to the body, headers, parsed_query or path
            headers:
              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
            body:
              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
            parsed_query:
              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
            path:
              type: string
              description: URL Encoded string of the value to match partially to the path
            cli_user_id:
              anyOf:
              - type: string
              - type: array
                items:
                  type: string
              nullable: true
              x-docs-hide: true
            issue_id:
              anyOf:
              - type: string
                maxLength: 255
              - type: array
                items:
                  type: string
                  maxLength: 255
              x-docs-hide: true
            event_data_id:
              anyOf:
              - type: string
                maxLength: 255
              - type: array
                items:
                  type: string
                  maxLength: 255
              x-docs-hide: true
            bulk_retry_id:
              anyOf:
              - type: string
                maxLength: 255
              - type: array
                items:
                  type: string
                  maxLength: 255
              x-docs-hide: true
          additionalProperties: false
          description: Filter for events to be included in the bulk cancel operation, use query parameters of [Event](#events)
          x-docs-force-simple-type: true
          x-docs-type: JSON
      - in: query
        name: query_partial_match
        schema:
          type: boolean
          description: Allow partial filter match on query property
      - in: query
        name: in_progress
        schema:
          type: boolean
          description: Indicates if the bulk cancel is currently in progress
      - 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
    post:
      operationId: createEventBulkCancel
      summary: Create events bulk cancel
      description: This endpoint creates and starts an events bulk cancel using the provided query.
      tags:
      - Bulk cancel events
      responses:
        '200':
          description: A single events bulk cancel
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchOperation'
        '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: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: object
                  properties:
                    id:
                      anyOf:
                      - type: string
                        maxLength: 255
                        description: Event ID
                      - type: array
                        items:
                          type: string
                          maxLength: 255
                          description: Event ID
                      description: Filter by event IDs
                    status:
                      anyOf:
                      - $ref: '#/components/schemas/EventStatus'
                      - type: array
                        items:
                          $ref: '#/components/schemas/EventStatus'
                      description: Lifecyle status of the event
                    webhook_id:
                      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
                    destination_id:
                      anyOf:
                      - type: string
                        maxLength: 255
                        description: Destination ID
                      - type: array
                        items:
                          type: string
                          maxLength: 255
                          description: Destination ID
                      description: Filter by destination IDs
                    source_id:
                      anyOf:
                      - type: string
                        maxLength: 255
                        description: Source ID
                      - type: array
                        items:
                          type: string
                          maxLength: 255
                          description: Source ID
                      description: Filter by source IDs
                    attempts:
                      anyOf:
                      - type: integer
                        minimum: 0
                      - $ref: '#/components/schemas/Operators'
                      description: Filter by number of attempts
                    response_status:
                      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
                    successful_at:
                      anyOf:
                      - type: string
                        format: date-time
                      - $ref: '#/components/schemas/Operators'
                      nullable: true
                      description: Filter by `successful_at` date using a date operator
                    created_at:
                      anyOf:
                      - type: string
                        format: date-time
                      - $ref: '#/components/schemas/Operators'
                      description: Filter by `created_at` date using a date operator
                    error_code:
                      anyOf:
                      - $ref: '#/components/schemas/AttemptErrorCodes'
                      - type: array
                        items:
                          $ref: '#/components/schemas/AttemptErrorCodes'
                      description: Filter by error code code
                    cli_id:
                      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.
                    last_attempt_at:
                      anyOf:
                      - type: string
                        format: date-time
                      - $ref: '#/components/schemas/Operators'
                      nullable: true
                      description: Filter by `last_attempt_at` date using a date operator
                    next_attempt_at:
                      anyOf:
                      - type: string
                        format: date-time
                      - $ref: '#/components/schemas/Operators'
                      nullable: true
                      description: Filter by `next_attempt_at` date using a date operator
                    search_term:
                      type: string
                      minLength: 3
                      description: URL Encoded string of the value to match partially to the body, headers, parsed_query or
                        path
                    headers:
                      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
                    body:
                      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
                    parsed_query:
                      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
                    path:
                      type: string
                      description: URL Encoded string of the value to match partially to the path
                    cli_user_id:
                      anyOf:
                      - type: string
                      - type: array
                        items:
                          type: string
                      nullable: true
                      x-docs-hide: true
                    issue_id:
                      anyOf:
                      - type: string
                        maxLength: 255
                      - type: array
                        items:
                          type: string
                          maxLength: 255
                      x-docs-hide: true
                    event_data_id:
                      anyOf:
                      - type: string
                        maxLength: 255
                      - type: array
                        items:
                          type: string
                          maxLength: 255
                      x-docs-hide: true
                    bulk_retry_id:
                      anyOf:
                      - type: string
                        maxLength: 255
                      - type: array
                        items:
                          type: string
                          maxLength: 255
                      x-docs-hide: true
                  additionalProperties: false
                  description: Filter properties for the events to be included in the bulk cancel
                  x-docs-force-simple-type: true
                  x-docs-type: JSON
              additionalProperties: false
  /bulk/events/cancel/plan:
    get:
      operationId: generateEventBulkCancelPlan
      summary: Generate events bulk cancel plan
      description: This endpoint estimates the number of events matched by the provided query before creating a bulk cancel.
      tags:
      - Bulk cancel events
      responses:
        '200':
          description: Events bulk cancel plan
          content:
            application/json:
              schema:
                type: object
                properties:
                  estimated_batch:
                    type: integer
                    nullable: true
                    description: Number of batches required to complete the bulk retry
                  estimated_count:
                    type: integer
                    nullable: true
                    description: Number of estimated events to be retried
                  progress:
                    type: number
                    format: float
                    nullable: true
                    description: Progression of the batch operations, values 0 - 1
                additionalProperties: false
        '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: query
        schema:
          type: object
          properties:
            id:
              anyOf:
              - type: string
                maxLength: 255
                description: Event ID
              - type: array
                items:
                  type: string
                  maxLength: 255
                  description: Event ID
              description: Filter by event IDs
            status:
              anyOf:
              - $ref: '#/components/schemas/EventStatus'
              - type: array
                items:
                  $ref: '#/components/schemas/EventStatus'
              description: Lifecyle status of the event
            webhook_id:
              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
            destination_id:
              anyOf:
              - type: string
                maxLength: 255
                description: Destination ID
              - type: array
                items:
                  type: string
                  maxLength: 255
                  description: Destination ID
              description: Filter by destination IDs
            source_id:
              anyOf:
              - type: string
                maxLength: 255
                description: Source ID
              - type: array
                items:
                  type: string
                  maxLength: 255
                  description: Source ID
              description: Filter by source IDs
            attempts:
              anyOf:
              - type: integer
                minimum: 0
              - $ref: '#/components/schemas/Operators'
              description: Filter by number of attempts
            response_status:
              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
            successful_at:
              anyOf:
              - type: string
                format: date-time
              - $ref: '#/components/schemas/Operators'
              nullable: true
              description: Filter by `successful_at` date using a date operator
            created_at:
              anyOf:
              - type: string
                format: date-time
              - $ref: '#/components/schemas/Operators'
              description: Filter by `created_at` date using a date operator
            error_code:
              anyOf:
              - $ref: '#/components/schemas/AttemptErrorCodes'
              - type: array
                items:
                  $ref: '#/components/schemas/AttemptErrorCodes'
              description: Filter by error code code
            cli_id:
              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.
            last_attempt_at:
              anyOf:
              - type: string
                format: date-time
              - $ref: '#/components/schemas/Operators'
              nullable: true
              description: Filter by `last_attempt_at` date using a date operator
            next_attempt_at:
              anyOf:
              - type: string
                format: date-time
              - $ref: '#/components/schemas/Operators'
              nullable: true
              description: Filter by `next_attempt_at` date using a date operator
            search_term:
              type: string
              minLength: 3
              description: URL Encoded string of the value to match partially to the body, headers, parsed_query or path
            headers:
              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
            body:
              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
            parsed_query:
              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
            path:
              type: string
              description: URL Encoded string of the value to match partially to the path
            cli_user_id:
              anyOf:
              - type: string
              - type: array
                items:
                  type: string
              nullable: true
              x-docs-hide: true
            issue_id:
              anyOf:
              - type: string
                maxLength: 255
              - type: array
                items:
                  type: string
                  maxLength: 255
              x-docs-hide: true
            event_data_id:
              anyOf:
              - type: string
                maxLength: 255
              - type: array
                items:
                  type: string
                  maxLength: 255
              x-docs-hide: true
            bulk_retry_id:
              anyOf:
              - type: string
                maxLength: 255
              - type: array
                items:
                  type: string
                  maxLength: 255
              x-docs-hide: true
          additionalProperties: false
          description: Filter properties for the events to be included in the bulk cancel
          x-docs-force-simple-type: true
          x-docs-type: JSON
  /bulk/events/cancel/{id}:
    get:
      operationId: getEventBulkCancel
      summary: Retrieve events bulk cancel
      description: This endpoint retrieves a specific events bulk cancel.
      tags:
      - Bulk cancel events
      responses:
        '200':
          description: A single events bulk cancel
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchOperation'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
      parameters:
      - in: path
        name: id
        schema:
          type: string
          description: Bulk cancel ID
        required: true
  /bulk/events/retry:
    get:
      operationId: getEventBulkRetries
      summary: Retrieve events bulk retries
      description: This endpoint lists events bulk retries.
      tags:
      - Bulk retry events
      responses:
        '200':
          description: List of events bulk retries
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchOperationPaginatedResult'
        '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: cancelled_at
        schema:
          anyOf:
          - type: string
            format: date-time
            nullable: true
          - $ref: '#/components/schemas/Operators'
          description: Filter by date the bulk retry was cancelled
      - in: query
        name: completed_at
        schema:
          anyOf:
          - type: string
            format: date-time
            nullable: true
          - $ref: '#/components/schemas/Operators'
          description: Filter by date the bulk retry completed
      - in: query
        name: created_at
        schema:
          anyOf:
          - type: string
            format: date-time
            nullable: true
          - $ref: '#/components/schemas/Operators'
          description: Filter by date the bulk retry was created
      - in: query
        name: id
        schema:
          anyOf:
          - type: string
            maxLength: 255
            description: Bulk retry ID
          - type: array
            items:
              type: string
              maxLength: 255
              description: Bulk retry ID
          description: Filter by bulk retry IDs
      - in: query
        name: query
        schema:
          type: object
          properties:
            id:
              anyOf:
              - type: string
                maxLength: 255
                description: Event ID
              - type: array
                items:
                  type: string
                  maxLength: 255
                  description: Event ID
              description: Filter by event IDs
            status:
              anyOf:
              - $ref: '#/components/schemas/EventStatus'
              - type: array

# --- truncated at 32 KB (99 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hookdeck/refs/heads/main/openapi/hookdeck-bulk-operations-api-openapi.yml
Hookdeck Bulk Operations API

Documentation

Specifications

Other Resources

OpenAPI Specification
