Skip to content
Dashboard
Theme
Theme

Verify webhook signatures

How to verify the OhAuthCat-Signature header on every webhook delivery, including the two signatures sent during secret rotation.

View Markdown

Verify the OhAuthCat-Signature header against the unchanged raw request bytes before JSON parsing. The signature is HMAC-SHA256 over the Unix timestamp, a period and those bytes, keyed with the entire whsec_… string. Freshness tolerance defaults to 300 seconds.

The SDK helpers compare signatures in constant time and validate the event envelope. During the 24-hour rotation overlap the producer sends two v1 signatures; retain the appropriate current/previous secrets during that window. Do not reserialize JSON before verification or disable freshness on an HTTP receiver.

Supply the framework’s raw byte buffer and original header. This function returns the verified event for durable processing; it does not acknowledge the HTTP request by itself.

import { webhooks } from "@ohauthcat/node";
const secret = process.env.OHAUTHCAT_WEBHOOK_SECRET;
if (!secret) throw new Error("Missing webhook secret");
export function receiveWebhook(rawBody, signatureHeader) {
return webhooks.verify(rawBody, signatureHeader, secret);
}

The existing Python development SDK exposes webhooks.verify. Use bytes from the request before a JSON middleware transforms them. No future Python client methods are needed here.

import os
from ohauthcat import webhooks
SECRET = os.environ["OHAUTHCAT_WEBHOOK_SECRET"]
if not SECRET:
raise ValueError("Missing webhook secret")
def receive_webhook(raw_body, signature_header):
return webhooks.verify(raw_body, signature_header, SECRET)

After verification, validate the event-specific data, deduplicate its ID and durably persist the work or effects before returning success. Reject invalid signatures, stale timestamps and malformed envelopes. A valid signature is not permission to apply data to a different environment or organization.

Avoid logging secrets, signatures or complete bodies. Check directory event handling for deprovisioning and retry behavior for duplicate deliveries.