Skip to Content
ZeroLeaksDocs
API reference

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:

HeaderValue
Content-Typeapplication/json
X-ZeroLeaks-Eventskills_scan.completed or skills_scan.failed
X-ZeroLeaks-Scan-IdThe skill scan ID
Idempotency-KeyscanId:event
X-ZeroLeaks-Signaturesha256= 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

BehaviorValue
ReceiverPublicly reachable over HTTPS. Private network destinations are rejected and redirects are not followed.
Timeout15 seconds per delivery
AttemptsUp to 5 in total
Wait between attempts1, 2, 4, then 8 minutes
Idempotency-KeyThe same on every attempt
OrderingEvents 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.

On this page