Verify webhook signatures

Open Connector signs Platform Webhooks and Trigger Webhook Subscription deliveries with Standard Webhooks. Verify each request with the signing secret for its destination or subscription. Do this before you trust the JSON body.

Install the verifier

Add the official JavaScript and TypeScript library to your receiver:

pnpm add standardwebhooks

Save the whsec_ secret that Open Connector returns when you create the destination or subscription in your server-side secret store. Platform Webhook creation and rotation reveal a new secret only once. Do not put it in browser code, logs, or source control.

Verify the received request

Read the body before any JSON parser changes it. Pass that body and the three webhook-* headers to Webhook.verify():

import { Webhook } from "standardwebhooks";

export async function verifyOpenConnectorWebhook(request: Request, secret: string): Promise<unknown> {
	if (!secret.startsWith("whsec_")) {
		throw new Error("Missing Open Connector webhook signing secret");
	}

	// Platform secrets use Base64URL. standardwebhooks expects standard Base64.
	const encoded = secret.slice("whsec_".length).replaceAll("-", "+").replaceAll("_", "/");
	const verifier = new Webhook(`whsec_${encoded}`);
	const rawBody = await request.text();

	return verifier.verify(rawBody, {
		"webhook-id": request.headers.get("webhook-id") ?? "",
		"webhook-timestamp": request.headers.get("webhook-timestamp") ?? "",
		"webhook-signature": request.headers.get("webhook-signature") ?? "",
	});
}

The standardwebhooks library checks the signature and rejects timestamps more than five minutes from the receiver's clock. It returns parsed JSON on success and throws on failure. Return a non-2xx response when verification fails. Validate the event shape before using its fields.

The Base64URL conversion changes only the secret's text encoding, not its key bytes. It also leaves the standard Base64 secrets used by Trigger Webhook Subscriptions unchanged. Do not parse and reserialize the request body before verification; even a whitespace change breaks the signature.

Handle retries and key rotation

Persist webhook-id with the work it authorizes so a retry does not repeat side effects. A valid signature and a recent timestamp do not provide durable deduplication.

During a normal Platform Webhook key rotation, each request carries signatures for the new and previous keys for up to 24 hours. The verifier accepts a request when any v1 signature matches the secret you supply. Put the new one-time secret into your receiver's secret store, then remove the previous secret after the overlap. An emergency rotation stops signing with previous keys immediately.

Use the signing secret, not an Open Connector API key, to verify deliveries. The receiver never needs to call Open Connector to check a signature.