Webhooks: payload, signatures and retries

Set webhook.url on a task and querying.ai POSTs the result there when the task reaches COMPLETED or FAILED.

curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "taskType": "PERPLEXITY",
    "idempotencyKey": "job-42:prompt-7:perplexity",
    "webhook": { "url": "https://hooks.example.com/querying" },
    "payload": { "prompt": "best wireless earbuds 2026", "country": "US" }
  }'

Delivery payload

Each delivery is a POST with Content-Type: application/json and this body:

Field	Type	Description
`task`	object	The task metadata, with its terminal `status`. `idempotencyKey` is present only if you sent one.
`credits`	object	`creditsCharged` is the settled charge, the same value a terminal poll shows. On a failed task, `creditsToCharge` is the task’s price and `creditsCharged` is `0`.
`response`	object	The engine result. On a failed task it is `{ "error": "<code>: <message>" }`.

For example, a completed Perplexity task (Perplexity costs 1 credit):

{
  "task": {
    "id": "8f2c1e40-...",
    "taskType": "PERPLEXITY",
    "status": "COMPLETED",
    "priority": 1,
    "createdAt": "2026-10-19T04:12:00.000Z",
    "idempotencyKey": "job-42:prompt-7:perplexity"
  },
  "credits": { "creditsToCharge": 1, "creditsCharged": 1 },
  "response": {
    "text": "The best wireless earbuds in 2026 are ...",
    "sources": [{ "position": 1, "url": "https://example.com/review", "label": "..." }]
  }
}

A failed task still delivers:

{
  "task": { "id": "8f2c1e40-...", "taskType": "PERPLEXITY", "status": "FAILED", "...": "..." },
  "credits": { "creditsToCharge": 1, "creditsCharged": 0 },
  "response": { "error": "ENGINE_TIMEOUT: The engine did not answer before the task deadline." }
}

Prices per task type are on Credits and limits. With include.citationAnalysis, the answer’s webhook waits until the attached analysis finishes, so you get both in one delivery. See Citation Analysis.

Verify the signature

Tasks submitted with an API key are signed with that key. Each delivery carries three headers:

Header	Value
`querying-webhook-id`	The message id: the task id for a task webhook, `batch_<id>` for a batch completion event. It is the same on every retry.
`querying-webhook-timestamp`	Unix seconds when the delivery was signed.
`querying-webhook-signature`	`v1,` followed by the base64 HMAC-SHA256 of `{id}.{timestamp}.{raw body}`.

The HMAC key is the 32-byte SHA-256 digest of the API key that submitted the task (for a batch, the key that created the batch). Compute the signature over the raw body before you parse it, compare in constant time, and accept timestamps within five minutes:

import base64
import hashlib
import hmac
import os
import time


def verify_webhook(headers, body: bytes) -> bool:
    """body is the raw request body, before json.loads."""
    message_id = headers["querying-webhook-id"]
    timestamp = headers["querying-webhook-timestamp"]
    key = hashlib.sha256(os.environ["QUERYING_API_KEY"].encode()).digest()
    signed = f"{message_id}.{timestamp}.".encode() + body
    digest = hmac.new(key, signed, hashlib.sha256).digest()
    expected = "v1," + base64.b64encode(digest).decode()
    given = headers.get("querying-webhook-signature", "")
    fresh = abs(time.time() - int(timestamp)) <= 300
    return fresh and hmac.compare_digest(expected, given)

import { createHash, createHmac, timingSafeEqual } from "node:crypto";

const key = createHash("sha256").update(process.env.QUERYING_API_KEY).digest();

// rawBody is the request body as a string, before JSON.parse.
export function verifyWebhook(headers, rawBody) {
  const id = headers["querying-webhook-id"];
  const timestamp = headers["querying-webhook-timestamp"];
  const digest = createHmac("sha256", key).update(`${id}.${timestamp}.${rawBody}`).digest("base64");
  const expected = Buffer.from(`v1,${digest}`);
  const given = Buffer.from(headers["querying-webhook-signature"] ?? "");
  const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) <= 300;
  return fresh && given.length === expected.length && timingSafeEqual(given, expected);
}

A delivery is unsigned only when the task has no API key, or for a batch whose API key was revoked more than 30 days earlier. If every task you create comes from an API key, reject requests without a valid signature.

After you rotate a key, tasks submitted with the new key are signed with the new key. Deliveries for tasks submitted earlier are still signed with the key that submitted them.

Retries

Return any 2xx within 30 seconds to acknowledge. Any other status, a timeout or a connection error is a failed attempt. Failed deliveries are retried after 2, 4, 8 and 16 minutes: five attempts in all over about 30 minutes, each with the same querying-webhook-id. After the fifth failure the delivery is abandoned. Redirects are not followed: a 3xx counts as a failed attempt. Delivery runs separately from the task. A task whose webhook never arrives still shows COMPLETED on GET /v1/async/task/{id}. To recover, poll within the 24-hour window described in Async tasks.

URL rules

webhook.url is checked at submit. A URL that breaks a rule is rejected with 400 VALIDATION_ERROR on the webhook.url field.

Rule	Detail
HTTPS only	`http://` is rejected.
Length	At most 2,048 characters.
No credentials	`https://user:pass@...` is rejected.
Public host	`localhost`, `.localhost`, `.internal` and private, loopback, link-local and other reserved IP addresses are rejected.

At delivery time the host must resolve only to public addresses, or the attempt fails. The connection goes to the address that was checked.

Write a safe handler

Verify, then acknowledge fast

Check the signature, store the payload durably, and return 200. Parse and write to your database afterwards, so a slow handler does not hit the 30-second timeout and cause a retry.

Deduplicate

Delivery is at least once. Skip a message whose querying-webhook-id you have already processed, or match on task.idempotencyKey and make the write idempotent.

Branch on status

Check task.status explicitly. A failed task also delivers a webhook, with response.error.

Batch completion event

A batch created with POST /v1/batches and a webhook.url sends each task’s result to that URL as above, then posts one completion event when every item has finished:

{
  "event": "batch.completed",
  "batch": {
    "id": "3f6b2a10-...",
    "status": "COMPLETED",
    "total": 2,
    "counts": { "pending": 0, "queued": 0, "processing": 0, "completed": 2, "failed": 0, "rejected": 0 },
    "createdAt": "2026-10-19T09:00:00.000Z",
    "completedAt": "2026-10-19T09:03:12.000Z",
    "webhook": { "url": "https://hooks.example.com/querying" },
    "metadata": null
  }
}

The event is signed with the batch’s API key, its querying-webhook-id is batch_<batch id>, and it follows the same retry schedule.

Get started

Core concepts

Answer engines

Search and web data

Request options

Research

GEO monitoring

Account and data

Webhooks: payload, signatures and retries

Delivery payload

Verify the signature

Retries

URL rules

Write a safe handler

Batch completion event

Next steps

Async tasks

Batches and grids

​Delivery payload

​Verify the signature

​Retries

​URL rules

​Write a safe handler

​Batch completion event

​Next steps

Async tasks

Batches and grids

Delivery payload

Verify the signature

Retries

URL rules

Write a safe handler

Batch completion event

Next steps