Webhooks
Receive skill scan completion events and verify the optional HMAC-SHA256 signature.
Asynchronous skill scans can send a webhook to your public HTTPS endpoint. Set webhookUrl and a private webhookSecret on the create request. Synchronous delivery does not send webhooks. Runtime and endpoint scans use polling rather than webhooks.
Request
ZeroLeaks sends an HTTP POST with a JSON body and these headers:
| Header | Value |
|---|---|
Content-Type | application/json |
X-ZeroLeaks-Event | skills_scan.completed or skills_scan.failed |
X-ZeroLeaks-Scan-Id | The skill scan ID |
Idempotency-Key | scanId:event |
X-ZeroLeaks-Signature | sha256= followed by a lowercase hex HMAC-SHA256 digest, when a secret was supplied |
Verify the signature
Verify the signature over the exact raw UTF-8 request body using your webhookSecret before parsing JSON. Compare digests in constant time. Reject unsigned events if your integration requires signatures. Keep the webhook secret separate from your ZeroLeaks API key.
Delivery and retries
| Behavior | Value |
|---|---|
| Receiver | Publicly reachable over HTTPS. Private network destinations are rejected and redirects are not followed. |
| Timeout | 15 seconds per delivery |
| Attempts | Up to 5 in total |
| Wait between attempts | 1, 2, 4, then 8 minutes |
Idempotency-Key | The same on every attempt |
| Ordering | Events are not ordered |
Store processed idempotency keys to avoid applying a delivery twice. If all attempts fail, poll the scan ID to get the result.