# Issue Triggers

![Issue Triggers](./images/issue-triggers.png)

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](/docs/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](#inspect-an-issue-trigger) it.
* [Deleting](#delete-an-issue-trigger) an issue trigger will also delete all associated issues.
* [Updating](#update-an-issue-trigger) an issue trigger will only affect generated issues after the update. Existing associated issues will be unaffected.

### Notification Channels

Specify which channels (email, Slack, Discord, Microsoft Teams, etc) should be used to notify you when an issue is triggered. To add a Notification Channel, read [Projects Integrations](/docs/platform/event-gateway-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:

| Rejection cause | Description |
| --- | --- |
| `SOURCE_DISABLED` | The source is disabled and not accepting requests |
| `NO_CONNECTION` | The source has no connections configured |
| `VERIFICATION_FAILED` | The request failed the source's verification check |
| `UNSUPPORTED_HTTP_METHOD` | The request used an HTTP method not supported by the source |
| `UNSUPPORTED_CONTENT_TYPE` | The request's content type is not supported |
| `UNPARSABLE_JSON` | The request body contains invalid JSON |
| `PAYLOAD_TOO_LARGE` | The request payload exceeds the maximum allowed size |
| `INGESTION_FATAL` | A fatal error occurred during request ingestion |
| `UNKNOWN` | The request was rejected for an unknown reason |

## 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.

### Dashboard
1. Open the [Issue Triggers](https://dashboard.hookdeck.com/issue-triggers) page to see a list of all issue triggers, grouped by type.

### API
`GET /2025-07-01/issue-triggers`

**Response example**
```json
{
  "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.

### Dashboard
1. Open the [Issues Triggers](https://dashboard.hookdeck.com/issue-triggers) page to see a list of all issue triggers, grouped by type.
2. Determine the desired trigger type and click the + Create button in the corresponding section.
3. Change the desired parameters for the given trigger's configuration.
4. Click the Create Trigger button.

### API
`POST /2025-07-01/issue-triggers`

**Request body example**
```json
{
  "type": "delivery",
  "configs": {
    "strategy": "first_attempt",
    "connections": "*"
  },
  "channels": {
    "email": {}
  }
}
```

**Response example**
```json
{
  "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.

### Dashboard
1. [Find your issue trigger](#view-issue-triggers) on the Issue Triggers page.
2. Click the issue trigger's description.From here you can view all issues associated with an issue trigger, [update the parameters](#update-an-issue-trigger) of the selected trigger, and define filters to better target and refine your notification strategy.

### API
`GET /2025-07-01/issue-triggers/:id`

**Response example**
```json
{
  "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.

### Dashboard
1. [Find your issue trigger](#view-issue-triggers) on the Issue Triggers page.
2. Click the issue trigger's description to [view the configuration](#inspect-an-issue-trigger).
3. Change the desired parameters for the given trigger's configuration.
4. Click Save for the configuration section to save the changes.

### API
`PUT /2025-07-01/issue-triggers/:id`

**Request body example**
```json
{
  "type": "delivery",
  "configs": {
    "strategy": "first_attempt",
    "connections": "*"
  },
  "channels": {
    "email": {}
  }
}
```

**Response example**
```json
{
  "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.

### Dashboard
1. [Find your issue trigger](#view-issue-triggers) on the Issue Triggers page.
2. Click the issue trigger's description to [view its configuration](#inspect-an-issue-trigger).
3. Click Delete at the bottom of the page.
4. Click Delete again to confirm.

### API
`DELETE /2025-07-01/issue-triggers/:id`

**Response example**
```json
{
  "id": "it_O9Um6FAQMQvxiP"
}
```