Skip to main content
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. The full event catalog with JSON schemas lives in the Svix portal.

Webhook Events | trunk.io - Svix

www.svix.com

​
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).
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.

​
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 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 for assistance.