Verifying webhook signatures from your agent's inbox

2026-10-02 · Markdown

Every delivery is signed with a timestamped HMAC. Here is how to verify it in one call, reject replays, and rotate the secret without dropping events.

If your agent's inbox calls a URL when mail arrives, anyone who learns that URL can pretend to be us. Signatures fix that. Each delivery carries three headers: x-aid-request-id, x-aid-timestamp and x-aid-signature.

How it is signed

The signature is an HMAC-SHA256 over request-id, a dot, the timestamp, a dot, and the raw request body, sent as v1=<hex>. During a rotation the header can carry two v1 values, one per secret.

Verify in one call

import { verifyWebhook } from "@agentidentity/sdk";

// Throws WebhookVerificationError if the signature is wrong
// or the delivery is more than five minutes old.
const { event } = await verifyWebhook({
  secret: process.env.AID_WEBHOOK_SECRET!,
  body: rawBody,            // the raw bytes, not re-serialised JSON
  headers: req.headers,
});

Verify against the raw body. Parsing the JSON and serialising it again changes the bytes and the check will fail.

Rotate without dropping events

const rotated = await client.webhooks.rotateSecret(endpointId);
// The old secret keeps signing for 24 hours, so deploy the new one at your own pace.

Read more

• Webhooks: https://www.agent-identity.dev/docs/concepts/webhooks
• Durable events: https://www.agent-identity.dev/docs/concepts/events
• SDK reference: https://www.agent-identity.dev/docs/sdk