Webhook

also known as: HMAC-signed webhook

An HTTP callback the API sends to a URL you register the moment a capture finishes, instead of you polling for it. For a monitoring pipeline running many prompts across many surfaces and regions, webhooks turn "was this done yet" from a poll loop into an event your system reacts to as it happens.

In AI Search API

Set webhook: { url, secret } on a request and each child job posts its terminal Envelope to that URL as soon as it completes, with X-AISearch-Signature and X-AISearch-Timestamp headers, an HMAC-SHA256 computed over the timestamp and the raw request body (`${timestamp}.${body}`) using your secret, so the receiving endpoint can verify the payload actually came from this API (and is not a stale replay) before trusting it. This is the mechanism visibility-monitoring and share-of-voice pipelines use to turn a nightly batch of hundreds of prompts into individual, verifiable, event-driven records instead of a poll loop against every child job id. A missing or unreachable endpoint never loses the result, the terminal Envelope is still retrievable by polling GET /v1/jobs/:childId, webhook or not.

POST /v1/search, registering a signed webhook

{
  "query": "…", "surfaces": ["chatgpt"],
  "webhook": { "url": "https://yourapp.com/hooks/aisearch", "secret": "whsec_…" }
}
// each child posts its terminal Envelope, headers:
// X-AISearch-Timestamp: <unix seconds>
// X-AISearch-Signature: <HMAC-SHA256 of "timestamp.body">

Related terms

See it in the product

Every definition here is enforced in the Envelope contract. Run a capture and read the fields yourself.

Start with 500 free credits All terms