HushSearchDocs

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

EventSent when
job.completedAn async job finished and its result is ready
job.failedAn async job stopped with an error
job.progressA 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 secret
  • X-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.