Webhook authentication

A V2 webhook has two layers of authentication. authentication_method chooses how Trio identifies itself to your notification URL: with a shared secret (url_secret) or with an OAuth token (oauth). On top of that, Trio signs every notification with the webhook’s notification_key, so you can check that the body came from Trio and was not changed on the way.

Coming from V1? The Secret you type in the Trio App is the notification_secret of the API, and the webhook key shown in the webhook details is the notification_key.

Authentication method

Set authentication_method when you register the webhook. The method decides which other fields the webhook needs.

Shared secret

A url_secret webhook needs notification_url and notification_secret. Trio sends the secret with every notification in the HTTP header x-webhook-secret, so your endpoint compares it with the value you stored and rejects the request when it differs.

OAuth

An oauth webhook needs oauth_client_id, oauth_client_secret, oauth_url and oauth_scope instead of notification_secret. Trio obtains an access token from oauth_url with those credentials and uses it to authenticate its requests to notification_url.

Field	Required	Description
`oauth_client_id`	Yes	OAuth client ID.
`oauth_client_secret`	Yes	OAuth client secret.
`oauth_url`	Yes	OAuth token URL Trio requests the token from.
`oauth_scope`	Yes	OAuth scope Trio requests.

Headers of a notification

Every notification is an HTTP POST with these headers:

Header	Value
`content-type`	`application/json`
`x-webhook-secret`	The webhook’s `notification_secret`.
`x-webhook-signature`	The HMAC-SHA-256 signature of the body, described below.

Signature

Every notification is signed with the webhook’s notification_key, the key Trio generates when the webhook is created. The key is returned by Create webhook and Get webhook, and shown in the webhook details of the Trio App. The signature travels in the HTTP header x-webhook-signature. Trio computes it over the exact bytes of the request body. To verify it:

Compute the HMAC-SHA-256 of the raw request body with notification_key as the key.
Encode the result as uppercase hexadecimal.
Compare it with the header value using a constant-time comparison.

import { createHmac, timingSafeEqual } from "crypto"

// rawBody is the request body exactly as received, before any JSON parsing
const expectedSignature = req.headers["x-webhook-signature"]
const signatureKey = "your_notification_key"

const computedSignature = createHmac("sha256", signatureKey)
	.update(rawBody)
	.digest("hex")
	.toUpperCase()

const isValid = timingSafeEqual(
	Buffer.from(expectedSignature),
	Buffer.from(computedSignature)
)

Sign the raw body, not a re-serialized copy. If your framework parses the JSON before your handler runs, JSON.stringify(req.body) can reorder keys or change number formatting and the signature will not match. Keep the raw body available to the handler.

A webhook created without a notification_key receives an empty x-webhook-signature header. Every webhook created through the API or the Trio App has a key. If your notification_key is accidentally made public, contact support. Trio rotates the key and coordinates the change with you.

Next steps

Content and structure: what is inside the body you just verified.
Events: every category and type Trio sends.
Creating your first webhook: where the secret and the key appear in the Trio App.

Getting started

API basics

Webhooks

Authentication method

Shared secret

OAuth

Headers of a notification

Signature

Next steps

​Authentication method

​Shared secret

​OAuth

​Headers of a notification

​Signature

​Next steps

Authentication method

Shared secret

OAuth

Headers of a notification

Signature

Next steps