> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trunk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Use webhooks to automate custom flaky test workflows

Trunk provides webhooks for you to build custom integrations to automate workflows, like notifying your team when a test becomes flaky or automatically creating tickets to investigate flaky tests. Trunk provides built-in connectors for [Linear](https://docs.trunk.io/flaky-tests/webhooks/linear-integration.md) and [Jira](https://docs.trunk.io/flaky-tests/webhooks/jira-integration.md) to automate ticket creation, and webhooks let you build custom integrations for use cases that are not supported out of the box.

> [!NOTE]
>
> **Creating tickets in Linear or Jira?** Trunk's built-in [automatic ticketing](https://docs.trunk.io/flaky-tests/management/ticketing/automatic-ticketing.md) is the recommended approach — it produces richer ticket bodies (failure history, impact, common failure reasons, code owners), manages the full ticket lifecycle (create, reopen, close), and has full dashboard support with tickets linked back to their test cases. Use webhooks for custom workflows or platforms without a built-in integration.

> [!NOTE]
>
> For Merge Queue webhook events (`pull_request.*` and `pull_request_batch.*`), see the [Merge Queue webhooks reference](https://docs.trunk.io/merge-queue/webhooks.md).

[Svix](https://docs.svix.com/) powers webhooks for Trunk. You'll be using Svix to configure webhooks and you should familiarize yourself with the [Svix App Portal docs](https://docs.svix.com/app-portal) to learn more.

## Supported Events

Trunk lets you create custom workflows with **event-triggered webhooks**. Flaky Tests events are named with a `test_case` prefix. You can find all the events that Trunk supports in the event catalog:

> [card] [Webhook Events | trunk.io - Svix](https://www.svix.com/event-types/us/org_2eQPL41Ew5XSHxiXZIamIUIXg8H/#v2.test_case.status_changed)
>
> [www.svix.com](http://www.svix.com)

Trunk publishes three Flaky Tests event types to Svix. Each event includes a full JSON schema with field descriptions visible in the Svix app portal.

## Test collection events

Every event carries a `test_collection` object with the ID of the [test collection](https://docs.trunk.io/flaky-tests/test-collections.md) the test belongs to and a link to it.

## Event payloads

### `test_case.monitor_status_changed`

Emitted when a monitor activates or resolves for a test case.

| Field | Type | Description |
| - | - | - |
| `type` | string | Always `test_case.monitor_status_changed` |
| `timestamp` | string (ISO 8601) | When the event occurred |
| `monitor.id` | string (UUID) | Unique identifier for the monitor |
| `monitor.type` | string | The type of monitor (e.g., `pass_on_retry`) |
| `monitor.status` | string | Current monitor status (`active` or `inactive`) |
| `evidence` | object | Data supporting the status change; structure varies by monitor type |
| `repository.id` | string (UUID) | Unique identifier for the repository |
| `repository.html_url` | string | URL of the repository |
| `test_case.id` | string (UUID) | Stable unique identifier for the test |
| `test_case.name` | string | Name of the test |
| `test_case.classname` | string | Test classname |
| `test_case.file_path` | string | File path of the test |
| `test_case.parent` | string | The parent test suite or file |
| `test_case.html_url` | string | URL to the test detail page in Trunk |
| `test_case.codeowners` | array of strings | Code owners associated with the test |
| `test_case.quarantined` | boolean | Whether the test is quarantined |
| `test_case.variant` | string | Test variant name |
| `test_case.bazel_label` | string | The Bazel label (target) of the test, when available. Omitted otherwise |

### `v2.test_case.status_changed`

Emitted when a test case changes status (e.g., becomes flaky or is resolved), as triggered by a monitor.

| Field | Type | Description |
| - | - | - |
| `type` | string | Always `v2.test_case.status_changed` |
| `timestamp` | string (ISO 8601) | When the event occurred |
| `previous_status` | string | The prior status of the test case |
| `new_status` | string | The updated status of the test case |
| `triggered_by.monitor_id` | string (UUID) | Unique identifier of the triggering monitor |
| `triggered_by.monitor_type` | string | Type of monitor that triggered the change |
| `triggered_by.monitor_status` | string | Status of the monitor at the time of the trigger |
| `repository` | object | See `repository` fields above |
| `test_case` | object | See `test_case` fields above |
| `test_case.failure_rate_last_7d` | number | The test's failure rate over the last 7 days, from 0 to 1 |
| `test_case.pull_requests_impacted_last_7d` | number | Distinct pull requests the test failed on, unquarantined, while flaky or broken, in the last 7 days |

### `v2.test_case.quarantining_setting_changed`

Emitted when someone sets a manual quarantining override on a test case. Fires on every change, including one that re-applies the value already in force. It does not fire when Trunk auto-quarantines a test.

| Field | Type | Description |
| - | - | - |
| `type` | string | Always `v2.test_case.quarantining_setting_changed` |
| `timestamp` | string (ISO 8601) | When the event occurred |
| `previous_quarantining_setting` | string | The setting before the change (`UNSPECIFIED`, `ALWAYS_QUARANTINE`, or `NEVER_QUARANTINE`) |
| `updated_quarantining_setting` | string | The setting after the change |
| `reason` | string or null | The comment left with the override, or null |
| `actor.email` | string | Email of the person who changed the setting |
| `actor.full_name` | string | Name of the person who changed the setting |
| `test_collection` | object | The test collection the test belongs to. Always present on this event |
| `repository` | object | See `repository` fields above |
| `test_case` | object | See `test_case` fields above |
| `test_case.failure_rate_last_7d` | number | The test's failure rate over the last 7 days, from 0 to 1 |
| `test_case.pull_requests_impacted_last_7d` | number | Distinct pull requests the test failed on, unquarantined, while flaky or broken, in the last 7 days |

**Delivery reliability.** If the webhook delivery provider rate-limits a request, Trunk automatically retries with exponential backoff, so a transient spike rarely drops an event. This applies to every Flaky Tests webhook event and needs no configuration on your side.

You can also find guides for specific examples here:

> [card] [Alert When a Test Escalates](https://docs.trunk.io/flaky-tests/recipes/alert-on-test-escalation.md)

> [card] [Send a Slack Message](https://docs.trunk.io/flaky-tests/webhooks/slack-integration.md)

> [card] [Create a GitHub Issue](https://docs.trunk.io/flaky-tests/webhooks/github-issues-integration.md)

> [card] [Send a Microsoft Teams Message](https://docs.trunk.io/flaky-tests/webhooks/microsoft-teams-integration.md)

> [card] [Create a Linear Issue](https://docs.trunk.io/flaky-tests/webhooks/linear-integration.md)

> [card] [Create a Jira Issue](https://docs.trunk.io/flaky-tests/webhooks/jira-integration.md)
