# Webhooks

Add `"webhook_url": "https://…"` to a job or a batch and WBX sends a signed `POST` when it finishes – no waiting, no polling.

## Events

`job.finished` (with status, exit code, duration, cost, file names and test results) or `batch.finished` (counts and cost of the whole batch).

```
{"event": "job.finished", "id": "job_…", "created_at": "2026-11-09T06:31:12Z", "data": {"id": "job_…", "status": "completed", "exit_code": 0, "cost": "0.000312 EUR", "test_results": […], …}}
```

**Python**

```
job = run_job(command="python analyze.py", webhook_url="https://example.com/hooks/wbx")
batch = run_batch(jobs, webhook_url="https://example.com/hooks/wbx")
```

**curl**

```
curl -s -X POST https://sandbox.wbx.cz/v1/jobs -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"command": "python analyze.py", "webhook_url": "https://example.com/hooks/wbx"}'
```

## Delivery and retries

- Only public `https://` addresses are accepted; redirects are not followed.
- Events are stored in a persistent queue before they are sent, so a restart of our servers does not lose them.
- A delivery counts only when your endpoint answers 2xx within 10 s; otherwise it is retried after 10 s, 1 min, 5 min, 30 min, 2 h, 6 h and 12 h.
- The same event can arrive more than once (e.g. when your answer was lost) – use the `id` to deduplicate, and the API remains the source of truth.

## Verifying the signature

Every request carries `X-WBX-Signature: t=<unix time>,v1=<hex>` – HMAC-SHA256 of `"<t>.<raw body>"` with your account's signing secret (API keys page in the portal, or `GET /v1/webhooks/secret`; rotate with `POST /v1/webhooks/secret/rotate`). Reject old timestamps (e.g. more than 5 minutes) to prevent replays. Each delivery also has `X-WBX-Event` and `X-WBX-Delivery`.

```
import hashlib, hmac, time

def verify(secret: str, body: bytes, header: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    if abs(time.time() - int(parts["t"])) > 300:
        return False
    mac = hmac.new(secret.encode(), parts["t"].encode() + b"." + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(mac, parts["v1"])
```

The Python SDK has the same check built in: `verify_webhook(secret, body, header)`, and `webhook_secret(rotate=False)` returns your secret.

Source: https://sandbox.wbx.cz/docs/jobs/webhooks
