# Webhooks

> Get an HTTP callback when an async job completes, fails or reports progress.

Source: http://localhost:3000/docs/endpoints/webhooks

**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`](http://localhost:3000/docs/endpoints/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

```bash
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.

```json
{
  "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 secret
- `X-HushSearch-Event` — the event name

```python

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 "")
```

```ts

  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

```bash
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.
