Issue Triggers

Issue triggers are the mechanism within Hookdeck to define which problems should trigger an issue (and a corresponding notification) and under which circumstances.

Behavior

Effective use of issue triggers relies on an understanding of their behavior and their relationship with the Issues they generate.

Generated Issues

Issues generated by an issue trigger are internally associated with that issue trigger.

• You can view an issue trigger's associated issues by inspecting it.
• Deleting an issue trigger will also delete all associated issues.
• Updating an issue trigger will only affect generated issues after the update. Existing associated issues will be unaffected.

Notification Channels

Specify which channels (email, Slack, etc) should be used to notify you when an issue is triggered. To add a Notification Channel, read Projects Integrations.

Trigger Overlap

It is possible to have multiple issue triggers of a given type that overlap in their coverage. In such cases, Hookdeck will attempt to select the most specific trigger and apply its logic.

For instance, if you had two Delivery triggers and a given connection occurs in the connections list of both triggers, the longer of the two lists would be considered more specific and only the more specific trigger would run for that connection. Similarly, a Request trigger configured with a specific rejection cause will take priority over one configured with '*' (all causes).

Issue Types

Issues are currently organized into four types -- delivery issues, transformation issues, backpressure issues, and request issues.

Delivery Issues

Delivery Issues describe issues related to the attempted delivery of requests, featuring two properties:

• strategy : 'first_attempt_failure' or 'last_attempt_failure'
• connections : a list of connections for which the trigger should be applied

Transformation Issues

Transformation Issues relate to issues that may occur in the data manipulation step of a request:

• log_level : the log level where the issue should be opened -- 'warn', 'error', or 'fatal'
• transformations : a list of transformations for which the trigger should be applied

Backpressure Issues

Backpressure Issues are caused when the estimated queue time (600,000ms, or 10 minutes, by default) exceeds the configured delay threshold. This allows for integration-specific alerts for impending queue processing issues.

• delay : the queue backpressure, in milliseconds, that should trigger an issue
• destinations : a list of destinations for which the trigger should be applied

Request Issues

Request Issues are triggered when incoming webhook requests are rejected by a source. This allows you to monitor and respond to problems with inbound request ingestion before they impact your event pipeline.

• rejection_causes : an array of specific rejection causes to match on, or '*' to match all rejection causes
• sources : a list of sources for which the trigger should be applied, a pattern to match on source names, or '*' for all sources

The possible rejection causes are:

Default Triggers

Each project is initialized with one issue trigger of each type:

• The default Delivery issue trigger will alert on the first attempt failure of all connections.
• The default Transformation issue trigger will alert for events on the warn log level of all transformations.
• The default Backpressure issue trigger will alert when the estimated queue time exceeds the default delay of 600000ms (10 minutes) for all destinations.
• The default Request issue trigger will alert on all rejection causes for all sources.

View issue triggers

Viewing issue triggers gives you an overview of the issue types you'll receive notifications about when they occur in your project. Each issue trigger corresponds to a specific issue type and the details necessary to trigger a notification.

{
  "pagination": {
    "order_by": "created_at",
    "dir": "desc",
    "limit": 100
  },
  "count": 1,
  "models": [
    {
      "id": "it_O9Um6FAQMQvxiP",
      "team_id": "tm_lbhzBKgFOUnB",
      "name": null,
      "type": "backpressure",
      "configs": {
        "delay": 600000,
        "destinations": "*"
      },
      "disabled_at": null,
      "updated_at": "2026-01-14T13:35:52.746Z",
      "created_at": "2026-01-14T13:35:52.806Z",
      "channels": {
        "email": {}
      }
    }
  ]
}

Create an issue trigger

Creating an issue trigger tells Hookdeck the circumstances under which an issue notification should be sent.

{
  "type": "delivery",
  "configs": {
    "strategy": "first_attempt",
    "connections": "*"
  },
  "channels": {
    "email": {}
  }
}

{
  "type": "delivery",
  "configs": {
    "strategy": "first_attempt",
    "connections": "*"
  },
  "channels": {
    "email": {}
  },
  "id": "it_BbDIsKCTbG8qck",
  "team_id": "tm_lbhzBKgFOUnB",
  "created_at": "2026-01-14T13:36:41.490Z",
  "name": null,
  "disabled_at": null,
  "updated_at": "2026-01-14T13:36:41.491Z"
}

Inspect an issue trigger

Inspecting an issue trigger gives you access to its context and activation configuration.

{
  "id": "it_O9Um6FAQMQvxiP",
  "team_id": "tm_lbhzBKgFOUnB",
  "name": null,
  "type": "backpressure",
  "configs": {
    "delay": 600000,
    "destinations": "*"
  },
  "disabled_at": null,
  "updated_at": "2026-01-14T13:35:52.746Z",
  "created_at": "2026-01-14T13:35:52.806Z",
  "channels": {
    "email": {}
  }
}

Update an issue trigger

Updating an issue trigger's configuration lets you define the activation context for when notifications get sent out.

Updates made to an issue trigger apply only to notifications and issues generated after the update. Issues associated with the trigger prior to any changes will be unaffected.

{
  "type": "delivery",
  "configs": {
    "strategy": "first_attempt",
    "connections": "*"
  },
  "channels": {
    "email": {}
  }
}

{
  "id": "it_O9Um6FAQMQvxiP",
  "team_id": "tm_lbhzBKgFOUnB",
  "name": null,
  "type": "backpressure",
  "configs": {
    "strategy": "first_attempt",
    "connections": "*"
  },
  "disabled_at": null,
  "updated_at": "2026-01-14T13:36:41.518Z",
  "created_at": "2026-01-14T13:35:52.806Z",
  "channels": {
    "email": {}
  }
}

Delete an issue trigger

Deleting an issue trigger prevents it from generating notifications.

Deleting an issue trigger will also permanently delete all associated issues.

{
  "id": "it_O9Um6FAQMQvxiP"
}