> ## Documentation Index
> Fetch the complete documentation index at: https://trunk-4cab4936-sam-gutentag-mq-webhooks-ft-cleanup.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Reference for Trunk Merge Queue webhook events, lifecycle, and payload behavior.

Trunk emits webhooks for Merge Queue events so you can react to PR and batch lifecycle changes from your own systems. Subscriptions are managed in the Trunk web app under **Merge Queue** → **Settings** → **Webhooks** and are powered by [Svix](https://docs.svix.com/). The full event catalog with JSON schemas lives in the Svix portal.

<Card horizontal icon="https://mintcdn.com/trunk-4cab4936-sam-gutentag-mq-webhooks-ft-cleanup/Y6AYH7f79ZOyiXZK/assets/_shared/svix.svg?fit=max&auto=format&n=Y6AYH7f79ZOyiXZK&q=85&s=6a2a6ab5d7ed1a4f8be8f9eb8c490d61" title="Webhook Events | trunk.io - Svix" href="https://www.svix.com/event-types/us/org_2eQPL41Ew5XSHxiXZIamIUIXg8H" width="347" height="347" data-path="assets/_shared/svix.svg">
  [www.svix.com](http://www.svix.com)
</Card>

***

### Subscribing to events

Merge Queue events fall into two families and each must be subscribed to explicitly:

* `pull_request.*` — events about an individual PR moving through the queue (queued, testing, merged, failed).
* `pull_request_batch.*` — events about a batch of PRs being tested together (for example, `pull_request_batch.pending_failure`).

<Note>
  If you only see `pull_request.*` events arriving at your endpoint, you likely haven't subscribed to the batch family. Edit the **Events** list on your webhook subscription in the Trunk web app and enable `pull_request_batch.*` entries.
</Note>

***

### Event lifecycle reference

A typical PR moves through the queue as follows:

1. The PR is added to the queue and a `pull_request.queued` event fires.
2. Once Trunk starts testing the PR (either alone or as part of a batch), a `pull_request.testing` event fires.
3. On a clean run, the PR merges and `pull_request.merged` fires.
4. If the PR is kicked from the queue at any point, `pull_request.failed` fires.

When a batch run reports failures, `pull_request_batch.pending_failure` fires for the batch. **This does not always lead to bisection.** If a PR higher in the queue fails first, the PRs above it can get kicked out and the surviving PRs are re-queued. The PRs that show up in subsequent `pull_request.queued` events won't necessarily map back to the original `pending_failure` batch.

When Trunk does run a bisection to identify the failing PR in a batch, there is no dedicated `bisection_completed` event. Instead, watch the `queued_reason` field on `pull_request.queued`:

* `BISECTION_REQUIRED` — the PR is entering bisection.
* `BISECTION_TEST_RUN_PASSED` — the PR passed its bisection test run and is returning to the queue.

***

### Multiple PRs in a batch

For most events the PR lifecycle and the batch lifecycle are the same — events fire per PR even when PRs are tested together. A 4-PR batch produces four `pull_request.testing` events, one per PR in the batch. `pull_request.failed` fires for each PR that is kicked out of the queue.

***

### Payload notes

All webhook payloads include an ISO 8601 `timestamp` field marking when the state transition occurred. Use this for ordering events rather than your endpoint's receive time — receive time is subject to retry delays and out-of-order delivery.

***

### Flaky Tests webhook events

`test_case.*` events — status changes (`v2.test_case.status_changed`), quarantining setting overrides, and AI investigation results — are part of Flaky Tests, not Merge Queue. See the [Flaky Tests webhooks reference](/flaky-tests/webhooks) for their payload schemas and usage.

***

### Getting help

If you or your team are running into issues with webhook subscriptions or payloads, contact [support@trunk.io](mailto:support@trunk.io) for assistance.