Webhooks
Get an HTTP callback when an async job completes, fails or reports progress.
GET /v1/webhooks/ — list your webhooks
POST /v1/webhooks/ — register a webhook
DELETE /v1/webhooks/{id} — remove a webhook
POST /v1/webhooks/{id}/test — send a signed test event
Webhooks tell your service when work submitted through /v1/jobs finishes, so you don't have to poll. You can also manage them from Dashboard → Webhooks.
Webhook management uses your dashboard session token (Authorization: Bearer <JWT>), not an API key.
Register a webhook
curl -X POST https://api.hushsearch.io/v1/webhooks/ \
-H "Authorization: Bearer YOUR_JWT" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-app.com/webhooks/hushsearch",
"events": ["job.completed", "job.failed"]
}'Response
The signing secret is returned once, on creation. Store it; later reads never include it.
{
"id": "5b0c3a1e-8f7d-4a8c-9b2f-2f1f0e6d3c11",
"url": "https://your-app.com/webhooks/hushsearch",
"events": ["job.completed", "job.failed"],
"active": true,
"created_at": "2026-09-26T10:00:00+00:00",
"secret": "k3Jx…"
}Events
| Event | Sent when |
|---|---|
job.completed | An async job finished and its result is ready |
job.failed | An async job stopped with an error |
job.progress | A long job reports progress |
Any other event name is rejected with HTTP 400.
Verify signatures
Every delivery carries:
X-HushSearch-Signature: sha256=<hex>— HMAC-SHA256 of the raw request body, keyed with your secretX-HushSearch-Event— the event name
import hashlib, hmac
def verify(raw_body: bytes, signature_header: str, secret: str) -> bool:
expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, signature_header or "")import { createHmac, timingSafeEqual } from "node:crypto";
export function verify(rawBody: Buffer, signatureHeader: string, secret: string) {
const expected = "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex");
const a = Buffer.from(expected);
const b = Buffer.from(signatureHeader ?? "");
return a.length === b.length && timingSafeEqual(a, b);
}Compute the HMAC over the bytes you received, before parsing JSON.
Test a webhook
curl -X POST https://api.hushsearch.io/v1/webhooks/5b0c3a1e-8f7d-4a8c-9b2f-2f1f0e6d3c11/test \
-H "Authorization: Bearer YOUR_JWT"Sends a signed test.ping event and returns {"success": true, "status_code": 200} when your endpoint answers, or {"success": false, "error": "…"}.
Delivery
Job webhooks are delivered by the webhook dispatcher with up to four attempts and exponential backoff. Respond with any 2xx status to acknowledge; anything else is retried.