Register a signed webhook on a search and receive the full Envelope when each child job reaches a terminal state — no polling required.
Webhooks are the recommended way to consume results from fan-out searches. Instead of polling GET /v1/jobs/:id, you register a webhook on a search and we deliver the complete Envelope to your endpoint the moment each child job reaches a terminal state.
One child is created per surface × region. You receive one webhook delivery per child, each carrying that child’s full Envelope. Prefer webhooks over polling whenever you request more than one surface or region.
The HTTPS endpoint that receives deliveries. The destination is SSRF-guarded: only http/https schemes are allowed, and private, loopback, and link-local addresses are rejected. Use a public HTTPS URL.
Signing secrets can be created, rotated, and revoked under /v1/webhooks/secrets. Rotate a secret if you suspect it has leaked; deliveries signed with the old secret keep verifying until you revoke it.
The full Envelope for this child — the same body returned by GET /v1/jobs/:childId.
A child can complete with nothing to report: if the surface returned no answer, the Envelope carries provenance.surfacePresent: false, a surface_absent warning, and an empty answer. The delivery type is still job.completed. Handle this as a normal, successful outcome.
Every delivery is signed with HMAC-SHA256 over the exact raw request bytes, encoded as lowercase hex, in the X-AISearch-Signature header.
Verify the signature against the raw body before parsing JSON. Compute the HMAC over the bytes you received, not over a re-serialized object — any reformatting changes the signature. Always compare using a timing-safe function.
import express from "express";import { createHmac, timingSafeEqual } from "node:crypto";const app = express();const SECRET = process.env.AISEARCH_WEBHOOK_SECRET;function verify(rawBody, header, secret) { const expected = createHmac("sha256", secret).update(rawBody).digest("hex"); const a = Buffer.from(expected); const b = Buffer.from(header ?? ""); return a.length === b.length && timingSafeEqual(a, b);}// Capture the raw bytes — do NOT use express.json() on this route.app.post( "/hooks/aisearch", express.raw({ type: "application/json" }), (req, res) => { const signature = req.get("X-AISearch-Signature"); if (!verify(req.body, signature, SECRET)) { return res.status(401).send("invalid signature"); } const event = JSON.parse(req.body.toString("utf8")); // Acknowledge fast, then process out of band. res.status(200).send("ok"); queueForProcessing(event); // e.g. push to a job queue });app.listen(3000);
Respond with any 2xx status as soon as you have verified and accepted the delivery. Do the heavy work — storing the Envelope, updating your records — asynchronously. A slow handler risks a timeout, which we treat as a failed delivery.
2
Non-2xx triggers a retry
Any non-2xx response (or a timeout) is considered a failure, and the delivery is retried with backoff. Retries reuse the same event id, so deduplicate on it to stay idempotent.
3
Deduplicate on event id
Because a delivery can arrive more than once, treat processing as at-least-once. Record each id you have handled and skip duplicates.
The delivery destination is validated for SSRF on every attempt: only http/https URLs are permitted, and requests to private, loopback, and link-local addresses are refused. Point your webhook at a publicly reachable HTTPS endpoint.
