# Verifying webhook signatures from your agent's inbox

*2026-10-02*

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

```ts
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

```ts
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

---
Docs: https://www.agent-identity.dev/docs · llms.txt: https://www.agent-identity.dev/llms.txt