ZeroLeaks skill scan webhooks
Receive ZeroLeaks asynchronous 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.
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 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. Store processed idempotency keys to avoid applying a delivery twice.
The receiver must be publicly reachable over HTTPS; private network destinations are rejected and redirects are not followed. Delivery has a 15-second timeout. Poll the scan ID to recover from failed delivery; do not assume automatic retries or an ordered event stream. Keep the webhook secret separate from your ZeroLeaks API key.