> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gavai.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Handle webhooks
> Receive gavAI events on your own endpoint, verify signatures, and dedupe retries.
export const ErrorTable = ({errors}) =>
;
export const Eyebrow = ({label, tone = "default"}) =>
{label}
;
By the end of this guide your endpoint accepts webhook POSTs from gavAI, rejects any request not cryptographically signed by your workspace, refuses replays older than five minutes, deduplicates retries on the event id, and answers inside the 10-second timeout. Plan on about 20 minutes if you already have a server with a route you can attach.
## Prerequisites
An HTTPS endpoint you control, reachable from the public internet — something like `https://api.acme.com/webhooks/gavai`. Local development works through a tunnel like `ngrok` or `cloudflared`.A webhook subscription added in the gavAI console at `console.gavai.app/settings/webhooks` — endpoint URL plus the event types you want.
## Steps
When you add a webhook in `console.gavai.app/settings/webhooks`, gavAI generates a signing secret of the form `whsec_<64 hex chars>`. The secret is shown **exactly once** — copy it to your secret manager immediately.
```text theme={null}
whsec_a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456
```
If you lose the secret, delete the webhook and create a new one. There is no retrieval endpoint.
Store the secret as an environment variable in your service:
```bash theme={null}
export GAVAI_WEBHOOK_SECRET="whsec_a1b2c3d4e5f6..."
```
Every webhook delivery includes three headers. All must be present — reject deliveries missing any of them before parsing the body.
", "HMAC-SHA256 signature over the timestamp and body hash. The v1= prefix is forward-compatible with future signature schemes."],
["X-Gavai-Webhook-Timestamp", "Unix seconds (integer string)", "Server time when the delivery was sent. Used with your server clock to detect replays."],
["X-Gavai-Webhook-Id", "UUIDv4", "Unique identifier for this delivery attempt. Changes on each retry — do not use it for deduplication."],
]}
/>
gavAI builds the signature as:
```text theme={null}
signed_str = "."
signature = hmac_sha256(signing_secret, signed_str)
header = "v1=" + hex(signature)
```
Your verifier reconstructs `signed_str` from the raw request body and the timestamp header, computes the same HMAC, and compares with a constant-time function.
Hash the **raw request bytes**, not a JSON-parsed-and-re-serialized version. Re-serializing changes whitespace and key ordering, producing a different hash and a failed verification. In Express, mount `express.raw({ type: "application/json" })` on the webhook route instead of `express.json()`.
```js Node.js theme={null}
import crypto from "node:crypto";
export function verifyGavaiWebhook(req, secret) {
const sigHeader = req.headers["x-gavai-webhook-signature"]; // "v1="
const ts = req.headers["x-gavai-webhook-timestamp"]; // ""
if (!sigHeader || !ts) return false;
if (!sigHeader.startsWith("v1=")) return false;
const skewSeconds = Math.abs(Math.floor(Date.now() / 1000) - Number(ts));
if (Number.isNaN(skewSeconds) || skewSeconds > 300) return false;
const bodySha = crypto
.createHash("sha256")
.update(req.rawBody) // raw bytes, NOT JSON-parsed text
.digest("hex");
const signed = `${ts}.${bodySha}`;
const expected = crypto
.createHmac("sha256", secret)
.update(signed)
.digest("hex");
const got = sigHeader.slice(3);
// Length check first — timingSafeEqual throws on mismatched lengths.
if (got.length !== expected.length) return false;
return crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected));
}
```
```python Python 3.10+ theme={null}
import hashlib
import hmac
import time
def verify_gavai_webhook(headers: dict, raw_body: bytes, secret: str) -> bool:
sig_header = headers.get("X-Gavai-Webhook-Signature", "")
ts = headers.get("X-Gavai-Webhook-Timestamp", "")
if not sig_header.startswith("v1="):
return False
if not ts.isdigit():
return False
if abs(int(time.time()) - int(ts)) > 300:
return False
body_sha = hashlib.sha256(raw_body).hexdigest()
signed = f"{ts}.{body_sha}".encode("ascii")
expected = hmac.new(secret.encode("utf-8"), signed, hashlib.sha256).hexdigest()
return hmac.compare_digest(sig_header[3:], expected)
```
An unsigned or invalid request is an attacker forging events to trigger side effects in your system. Reject any failed verification with `401 Unauthorized` before processing the payload.
The verifiers above already enforce this, but it is worth calling out: reject any delivery where `X-Gavai-Webhook-Timestamp` is more than **±5 minutes** off your server clock.
```js theme={null}
const skewSeconds = Math.abs(Math.floor(Date.now() / 1000) - Number(ts));
if (skewSeconds > 300) return false; // 300 seconds = 5 minutes
```
Without this check, a captured delivery could be replayed against your endpoint days later. The HMAC still verifies — the timestamp window is your replay protection.
Keep the server clock synced via NTP. A drifted clock causes legitimate deliveries to fail the window check.
gavAI retries failed deliveries up to **5 times** with increasing delays: roughly **1 s, 5 s, 30 s, 5 min, 1 hr**. Each retry carries a fresh `X-Gavai-Webhook-Id` header — do not use that for deduplication.
Use the `id` field inside the JSON body, which stays constant across retries:
```js theme={null}
app.post("/webhooks/gavai", express.raw({ type: "application/json" }), async (req, res) => {
if (!verifyGavaiWebhook(req, process.env.GAVAI_WEBHOOK_SECRET)) {
return res.status(401).send("Invalid signature");
}
const event = JSON.parse(req.body.toString());
const eventId = event.id; // stable across retries
if (await db.events.exists(eventId)) {
return res.status(200).send("Already processed");
}
await db.events.insert(eventId);
// ... handle the event ...
res.status(200).send("OK");
});
```
Store processed event ids in a database or cache with a TTL that covers the maximum retry window (last retry \~1 hour out, plus margin — a 24-hour TTL is safe).
gavAI expects a `2xx` response within **10 seconds**. Beyond that, the delivery is marked failed and a retry is scheduled. Move slow work — emails, third-party API calls, analytics — to a background queue and acknowledge fast:
```js theme={null}
app.post("/webhooks/gavai", express.raw({ type: "application/json" }), async (req, res) => {
if (!verifyGavaiWebhook(req, process.env.GAVAI_WEBHOOK_SECRET)) {
return res.status(401).send("Invalid signature");
}
const event = JSON.parse(req.body.toString());
// Enqueue for background processing — respond immediately.
await queue.push({ event });
res.status(200).send("Queued");
});
```
After 5 consecutive deliveries each exhaust all 5 retries, gavAI opens a **circuit breaker** for 1 hour and pauses all deliveries to your endpoint. Once you have fixed the underlying issue, click **Send test event** in `console.gavai.app/settings/webhooks` to re-probe after the cool-down.
## Troubleshooting
## What you built
You registered a webhook and stored the signing secret, read and validated the three delivery headers, implemented HMAC-SHA256 verification with constant-time comparison, added replay protection via the timestamp window, deduplicated retries on the body `id`, and structured the handler to respond inside the 10-second timeout. Your endpoint is now safe to receive and process gavAI events.
## Next steps
Event types, payload schemas, and how to manage subscriptions in the console.
The full signing algorithm, test vectors, and examples in Go and Rust.
Retry schedule, circuit breaker rules, and how to recover a paused endpoint.