Webhooks

Documentation on the various webhooks that are provided by Trunk products

Trunk provides a variety of webhooks to allow responding to various events from Trunk. Each event corresponds to a Trunk product and an action within that product (for example, a Pull Request being submitted to Trunk Merge).

Overview

Webhooks for Trunk are powered by Svix - their documents on consuming webhooks apply here as well.

Where To Find

To configure Trunk to send webhooks in response to certain events, go to the Settings page. Under "Organization", go to the "Webhooks" section. From there, you'll be able to configure everything around webhooks.

Send Webhooks to an Endpoint

In the "Endpoints" tab, you'll be able to configure sending webhooks to a predetermined endpoint you have set up by clicking the "Add Endpoint" button.

If you don't currently have an endpoint ready to receive webhooks, you can quickly set up a URL for testing by clicking the "use Svix Play" link - you'll be able to inspect all webhook events sent there.

From there, you can subscribe to the specific webhooks you want to be emitted to your provided URL.

Svix's docs on this can be found here.

Verifying Webhooks

Since webhooks are posted to an endpoint that you provide, it's possible for attackers to impersonate Trunk by simply sending a fake webhook to your endpoint. To prevent this, every webhook (and its associated metadata) emitted by Trunk is signed - this signature can be used to verify that the webhook is certainly from Trunk.

Another possible vulnerability is replay attacks, where an attacker intercepts a webhook, takes its signature, then uses it for a malicious payload. To help prevent this, webhooks include a timestamp for when the webhook attempt occurred, which is can be used do determine whether or not the webhook was emitted recently.

Svix provides a library in order to allow easily verifying these webhook signatures. Docs on how to set this up can be found here. If you wish to verify webhooks manually instead, you can find Svix docs on how to so that here.

Event Catalogue

In the "Event Catalogue" tab, you can view all possible webhooks emitted by Trunk.

Svix's docs on this can be found here.

Monitoring and Testing Webhooks

From the "Logs" and "Activity" tabs, it's possible to view all emitted webhooks and their payloads and search them, examine the responses returned to us after processing a webhook and which ones failed, and resend webhook events. This allows you to have full insight into how your system is handling webhooks from Trunk.