Hookdeck Issues API

Track issues that occur on events, requests, and backpressure, and manage the triggers (rules) that open and route issues to Slack, Email, Microsoft Teams, Discord, BetterUptime, and other channels.

Hookdeck Issues API is one of 12 APIs that Hookdeck publishes on the APIs.io network, described by a machine-readable OpenAPI specification.

This API exposes 4 machine-runnable capabilities that can be deployed as REST, MCP, or Agent Skill surfaces via Naftiko and 1 JSON Schema definition.

Tagged areas include Issues, Issue Triggers, and Observability. The published artifact set on APIs.io includes API documentation, an OpenAPI specification, 4 Naftiko capability specs, and 1 JSON Schema.

OpenAPI Specification

hookdeck-issues-api-openapi.yml Raw ↑
openapi: 3.0.1
info:
  title: Hookdeck Issues API
  version: 1.0.0
  description: Track issues that occur on events, requests, and backpressure, and manage the triggers (rules) that open and
    route issues to Slack, Email, Teams, Discord, BetterUptime, and other channels.
  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: Issues
  description: Issues lets you track problems in your project and communicate resolution steps with your team.
- name: Issue Triggers
  description: Issue Triggers lets you setup rules that trigger issues when certain conditions are met.
paths:
  /issue-triggers:
    get:
      operationId: getIssueTriggers
      summary: Retrieve issue triggers
      description: This endpoint lists issue triggers.
      tags:
      - Issue Triggers
      responses:
        '200':
          description: List of issue triggers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IssueTriggerPaginatedResult'
        '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: name
        schema:
          type: string
          maxLength: 255
          description: Filter by issue trigger name
      - in: query
        name: type
        schema:
          anyOf:
          - $ref: '#/components/schemas/IssueType'
          - type: array
            items:
              $ref: '#/components/schemas/IssueType'
      - in: query
        name: disabled_at
        schema:
          anyOf:
          - type: string
            format: date-time
            nullable: true
          - $ref: '#/components/schemas/Operators'
          description: Date when the issue trigger was disabled
      - in: query
        name: order_by
        schema:
          anyOf:
          - type: string
            maxLength: 255
            enum:
            - created_at
            - type
          - type: array
            items:
              type: string
              maxLength: 255
              enum:
              - created_at
              - type
            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: createIssueTrigger
      summary: Create an issue trigger
      description: This endpoint creates an issue trigger.
      tags:
      - Issue Triggers
      responses:
        '200':
          description: A single issue trigger
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IssueTrigger'
        '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:
                type:
                  $ref: '#/components/schemas/IssueType'
                configs:
                  anyOf:
                  - $ref: '#/components/schemas/IssueTriggerDeliveryConfigs'
                  - $ref: '#/components/schemas/IssueTriggerTransformationConfigs'
                  - $ref: '#/components/schemas/IssueTriggerBackpressureConfigs'
                  - $ref: '#/components/schemas/IssueTriggerRequestConfigs'
                  description: Configuration object for the specific issue type selected
                channels:
                  $ref: '#/components/schemas/IssueTriggerChannels'
                name:
                  type: string
                  maxLength: 255
                  nullable: true
                  description: Optional unique name to use as reference when using the API
              required:
              - type
              - channels
              additionalProperties: false
    put:
      operationId: upsertIssueTrigger
      summary: Create/Update an issue trigger
      description: This endpoint creates an issue trigger, or updates an existing issue trigger by name.
      tags:
      - Issue Triggers
      responses:
        '200':
          description: A single issue trigger
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IssueTrigger'
        '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:
                type:
                  $ref: '#/components/schemas/IssueType'
                configs:
                  anyOf:
                  - $ref: '#/components/schemas/IssueTriggerDeliveryConfigs'
                  - $ref: '#/components/schemas/IssueTriggerTransformationConfigs'
                  - $ref: '#/components/schemas/IssueTriggerBackpressureConfigs'
                  - $ref: '#/components/schemas/IssueTriggerRequestConfigs'
                  description: Configuration object for the specific issue type selected
                channels:
                  $ref: '#/components/schemas/IssueTriggerChannels'
                name:
                  type: string
                  maxLength: 255
                  description: Required unique name to use as reference when using the API
              required:
              - type
              - channels
              - name
              additionalProperties: false
  /issue-triggers/{id}:
    get:
      operationId: getIssueTrigger
      summary: Retrieve an issue trigger
      description: This endpoint retrieves a specific issue trigger.
      tags:
      - Issue Triggers
      responses:
        '200':
          description: A single issue trigger
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IssueTrigger'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
      parameters:
      - in: path
        name: id
        schema:
          type: string
          description: Issue trigger ID
        required: true
    put:
      operationId: updateIssueTrigger
      summary: Update an issue trigger
      description: This endpoint updates an issue trigger.
      tags:
      - Issue Triggers
      responses:
        '200':
          description: A single issue trigger
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IssueTrigger'
        '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: path
        name: id
        schema:
          type: string
          description: Issue trigger ID
        required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                configs:
                  anyOf:
                  - $ref: '#/components/schemas/IssueTriggerDeliveryConfigs'
                  - $ref: '#/components/schemas/IssueTriggerTransformationConfigs'
                  - $ref: '#/components/schemas/IssueTriggerBackpressureConfigs'
                  - $ref: '#/components/schemas/IssueTriggerRequestConfigs'
                  description: Configuration object for the specific issue type selected
                channels:
                  $ref: '#/components/schemas/IssueTriggerChannels'
                disabled_at:
                  type: string
                  format: date-time
                  nullable: true
                  description: Date when the issue trigger was disabled
                name:
                  type: string
                  maxLength: 255
                  nullable: true
                  description: Optional unique name to use as reference when using the API
              additionalProperties: false
    delete:
      operationId: deleteIssueTrigger
      summary: Delete an issue trigger
      description: This endpoint permanently deletes an issue trigger. This action cannot be undone.
      tags:
      - Issue Triggers
      responses:
        '200':
          description: An object with deleted issue trigger's id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeletedIssueTriggerResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
      parameters:
      - in: path
        name: id
        schema:
          type: string
          description: Issue trigger ID
        required: true
  /issue-triggers/{id}/disable:
    put:
      operationId: disableIssueTrigger
      summary: Disable an issue trigger
      description: This endpoint disables an issue trigger so it stops producing issues.
      tags:
      - Issue Triggers
      responses:
        '200':
          description: A single issue trigger
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IssueTrigger'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
      parameters:
      - in: path
        name: id
        schema:
          type: string
          description: Issue trigger ID
        required: true
  /issue-triggers/{id}/enable:
    put:
      operationId: enableIssueTrigger
      summary: Enable an issue trigger
      description: This endpoint enables a previously disabled issue trigger.
      tags:
      - Issue Triggers
      responses:
        '200':
          description: A single issue trigger
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IssueTrigger'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
      parameters:
      - in: path
        name: id
        schema:
          type: string
          description: Issue trigger ID
        required: true
  /issues:
    get:
      operationId: getIssues
      summary: Retrieve issues
      description: This endpoint lists issues, or a subset of issues.
      tags:
      - Issues
      responses:
        '200':
          description: List of issues
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IssueWithDataPaginatedResult'
        '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
            example: iss_YXKv5OdJXCiVwkPhGy
          - type: array
            items:
              type: string
              maxLength: 255
              example: iss_YXKv5OdJXCiVwkPhGy
          description: Filter by Issue IDs
      - in: query
        name: issue_trigger_id
        schema:
          anyOf:
          - type: string
            maxLength: 255
            description: Issue trigger ID
            example: it_BXKv5OdJXCiVwkPhGy
          - type: array
            items:
              type: string
              maxLength: 255
              description: Issue trigger ID
              example: it_BXKv5OdJXCiVwkPhGy
          description: Filter by Issue trigger IDs
      - in: query
        name: type
        schema:
          anyOf:
          - type: string
            enum:
            - delivery
            - transformation
            - backpressure
            - request
            description: Issue type
            example: delivery
          - type: array
            items:
              type: string
              enum:
              - delivery
              - transformation
              - backpressure
              - request
              description: Issue type
              example: delivery
          description: Filter by Issue types
      - in: query
        name: status
        schema:
          anyOf:
          - type: string
            enum:
            - OPENED
            - IGNORED
            - ACKNOWLEDGED
            - RESOLVED
            description: Issue status
            example: OPENED
          - type: array
            items:
              type: string
              enum:
              - OPENED
              - IGNORED
              - ACKNOWLEDGED
              - RESOLVED
              description: Issue status
              example: OPENED
          description: Filter by Issue statuses
      - in: query
        name: merged_with
        schema:
          anyOf:
          - type: string
            description: Issue ID
            example: iss_AXKv3OdJXCiKlkPhDz
          - type: array
            items:
              type: string
              description: Issue ID
              example: iss_AXKv3OdJXCiKlkPhDz
          description: Filter by Merged Issue IDs
      - in: query
        name: aggregation_keys
        schema:
          type: object
          properties:
            webhook_id:
              anyOf:
              - type: string
              - type: array
                items:
                  type: string
            response_status:
              anyOf:
              - type: number
                format: float
              - type: array
                items:
                  type: number
                  format: float
            error_code:
              anyOf:
              - $ref: '#/components/schemas/AttemptErrorCodes'
              - type: array
                items:
                  $ref: '#/components/schemas/AttemptErrorCodes'
            transformation_id:
              anyOf:
              - type: string
              - type: array
                items:
                  type: string
            log_level:
              anyOf:
              - type: string
                enum:
                - debug
                - info
                - warn
                - error
                - fatal
              - type: array
                items:
                  type: string
                  enum:
                  - debug
                  - info
                  - warn
                  - error
                  - fatal
            destination_id:
              anyOf:
              - type: string
              - type: array
                items:
                  type: string
            delay:
              anyOf:
              - type: number
                format: float
              - type: array
                items:
                  type: number
                  format: float
            source_id:
              anyOf:
              - type: string
              - type: array
                items:
                  type: string
            rejection_cause:
              anyOf:
              - $ref: '#/components/schemas/RequestRejectionCause'
              - type: array
                items:
                  $ref: '#/components/schemas/RequestRejectionCause'
          additionalProperties: false
          description: Filter by aggregation keys
          x-docs-force-simple-type: true
          x-docs-type: JSON
      - in: query
        name: created_at
        schema:
          anyOf:
          - type: string
            format: date-time
            nullable: true
          - $ref: '#/components/schemas/Operators'
          description: Filter by created dates
      - in: query
        name: first_seen_at
        schema:
          anyOf:
          - type: string
            format: date-time
            nullable: true
          - $ref: '#/components/schemas/Operators'
          description: Filter by first seen dates
      - in: query
        name: last_seen_at
        schema:
          anyOf:
          - type: string
            format: date-time
            nullable: true
          - $ref: '#/components/schemas/Operators'
          description: Filter by last seen dates
      - in: query
        name: dismissed_at
        schema:
          anyOf:
          - type: string
            format: date-time
            nullable: true
          - $ref: '#/components/schemas/Operators'
          description: Filter by dismissed dates
      - in: query
        name: order_by
        schema:
          anyOf:
          - type: string
            maxLength: 255
            enum:
            - created_at
            - first_seen_at
            - last_seen_at
            - opened_at
            - status
          - type: array
            items:
              type: string
              maxLength: 255
              enum:
              - created_at
              - first_seen_at
              - last_seen_at
              - opened_at
              - status
            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
  /issues/count:
    get:
      operationId: getIssueCount
      summary: Get the number of issues
      description: ''
      tags:
      - Issues
      responses:
        '200':
          description: Issue count
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IssueCount'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
      parameters:
      - in: query
        name: id
        schema:
          anyOf:
          - type: string
            maxLength: 255
            example: iss_YXKv5OdJXCiVwkPhGy
          - type: array
            items:
              type: string
              maxLength: 255
              example: iss_YXKv5OdJXCiVwkPhGy
          description: Filter by Issue IDs
      - in: query
        name: issue_trigger_id
        schema:
          anyOf:
          - type: string
            maxLength: 255
            description: Issue trigger ID
            example: it_BXKv5OdJXCiVwkPhGy
          - type: array
            items:
              type: string
              maxLength: 255
              description: Issue trigger ID
              example: it_BXKv5OdJXCiVwkPhGy
          description: Filter by Issue trigger IDs
      - in: query
        name: type
        schema:
          anyOf:
          - type: string
            enum:
            - delivery
            - transformation
            - backpressure
            - request
            description: Issue type
            example: delivery
          - type: array
            items:
              type: string
              enum:
              - delivery
              - transformation
              - backpressure
              - request
              description: Issue type
              example: delivery
          description: Filter by Issue types
      - in: query
        name: status
        schema:
          anyOf:
          - type: string
            enum:
            - OPENED
            - IGNORED
            - ACKNOWLEDGED
            - RESOLVED
            description: Issue status
            example: OPENED
          - type: array
            items:
              type: string
              enum:
              - OPENED
              - IGNORED
              - ACKNOWLEDGED
              - RESOLVED
              description: Issue status
              example: OPENED
          description: Filter by Issue statuses
      - in: query
        name: merged_with
        schema:
          anyOf:
          - type: string
            description: Issue ID
            example: iss_AXKv3OdJXCiKlkPhDz
          - type: array
            items:
              type: string
              description: Issue ID
              example: iss_AXKv3OdJXCiKlkPhDz
          description: Filter by Merged Issue IDs
      - in: query
        name: aggregation_keys
        schema:
          type: object
          properties:
            webhook_id:
              anyOf:
              - type: string
              - type: array
                items:
                  type: string
            response_status:
              anyOf:
              - type: number
                format: float
              - type: array
                items:
                  type: number
                  format: float
            error_code:
              anyOf:
              - $ref: '#/components/schemas/AttemptErrorCodes'
              - type: array
                items:
                  $ref: '#/components/schemas/AttemptErrorCodes'
            transformation_id:
              anyOf:
              - type: string
              - type: array
                items:
                  type: string
            log_level:
              anyOf:
              - type: string
                enum:
                - debug
                - info
                - warn
                - error
                - fatal
              - type: array
                items:
                  type: string
                  enum:
                  - debug
                  - info
                  - warn
                  - error
                  - fatal
            destination_id:
              anyOf:
              - type: string
              - type: array
                items:
                  type: string
            delay:
              anyOf:
              - type: number
                format: float
              - type: array
                items:
                  type: number
                  format: float
            source_id:
              anyOf:
              - type: string
              - type: array
                items:
                  type: string
            rejection_cause:
              anyOf:
              - $ref: '#/components/schemas/RequestRejectionCause'
              - type: array
                items:
                  $ref: '#/components/schemas/RequestRejectionCause'
          additionalProperties: false
          description: Filter by aggregation keys
          x-docs-force-simple-type: true
          x-docs-type: JSON
      - in: query
        name: created_at
        schema:
          anyOf:
          - type: string
            format: date-time
            nullable: true
          - $ref: '#/components/schemas/Operators'
          description: Filter by created dates
      - in: query
        name: first_seen_at
        schema:
          anyOf:
          - type: string
            format: date-time
            nullable: true
          - $ref: '#/components/schemas/Operators'
          description: Filter by first seen dates
      - in: query
        name: last_seen_at
        schema:
          anyOf:
          - type: string
            format: date-time
            nullable: true
          - $ref: '#/components/schemas/Operators'
          description: Filter by last seen dates
      - in: query
        name: dismissed_at
        schema:
          anyOf:
          - type: string
            format: date-time
            nullable: true
          - $ref: '#/components/schemas/Operators'
          description: Filter by dismissed dates
      - in: query
        name: order_by
        schema:
          anyOf:
          - type: string
            maxLength: 255
            enum:
            - created_at
            - first_seen_at
            - last_seen_at
            - opened_at
            - status
          - type: array
            items:
              type: string
              maxLength: 255
              enum:
              - created_at
              - first_seen_at
              - last_seen_at
              - opened_at
              - status
            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
  /issues/{id}:
    get:
      operationId: getIssue
      summary: Retrieve an issue
      description: This endpoint retrieves a specific issue.
      tags:
      - Issues
      responses:
        '200':
          description: A single issue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IssueWithData'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
      parameters:
      - in: path
        name: id
        schema:
          type: string
          description: Issue ID
        required: true
    put:
      operationId: updateIssue
      summary: Update an issue
      description: This endpoint updates an issue's status.
      tags:
      - Issues
      responses:
        '200':
          description: Updated issue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Issue'
        '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: path
        name: id
        schema:
          type: string
          description: Issue ID
        required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                  enum:
                  - OPENED
                  - IGNORED
                  - ACKNOWLEDGED
                  - RESOLVED
                  description: New status
              required:
              - status
              additionalProperties: false
    delete:
      operationId: dismissIssue
      summary: Dismiss an issue
      description: This endpoint dismisses an issue.
      tags:
      - Issues
      responses:
        '200':
          description: Dismissed issue
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Issue'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
      parameters:
      - in: path
        name: id
        schema:
          type: string
          description: Issue ID
        required: true
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    basicAuth:
      type: http
      scheme: basic
  schemas:
    DestinationConfigHTTPAuthOAuth2ClientCredentials:
      type: object
      properties:
        auth_server:
          type: string
        client_id:
          type: string
        client_secret:
          type: string
        scope:
          type: string
        authentication_type:
          type: string
          enum:
          - basic
          - bearer
          - x-www-form-urlencoded
      additionalProperties: false
      x-docs-type: OAUTH2_CLIENT_CREDENTIALS
    IssueTriggerSlackChannel:
      type: object
      properties:
        channel_name:
          type: string
      required:
      - channel_name
      additionalProperties: false
      description: Channel for a 'Slack' issue trigger
    EventStatus:
      type: string
      enum:
      - SCHEDULED
      - QUEUED
      - HOLD
      - SUCCESSFUL
      - FAILED
      - CANCELLED
    IssueTrigger:
      type: object
      properties:
        id:
          type: string
          description: ID of the issue trigger
        team_id:
          type: string
          nullable: true
          description: ID of the project
        name:
          type: string
          nullable: true
          description: Optional unique name to use as reference when using the API
        type:
          $ref: '#/components/schemas/IssueType'
        configs:
          $ref: '#/components/schemas/IssueTriggerReference'
        channels:
          $ref: '#/components/schemas/IssueTriggerChannels'
        disabled_at:
          type: string
          format: date-time
          nullable: true
          description: ISO timestamp for when the issue trigg

# --- truncated at 32 KB (90 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hookdeck/refs/heads/main/openapi/hookdeck-issues-api-openapi.yml