API Reference

Verify webhook signatures

Authenticate the exact raw request body with HMAC-SHA256.

Signature format

Name	Type	Description
`Algorithm`	HMAC-SHA256	Hex digest of raw UTF-8 body.
`Header`	X-Zippy-Signature	Format sha256=<hex>.
`Signed material`	raw body	Exact JSON string POSTed — not pretty-printed recomputation.

Language support

Verification examples are available for JavaScript, Python, PHP, Go, Java, and Ruby. The simulator also generates a signed cURL request for testing your receiver.

Verification playground

Webhook test simulator

Select an event, generate its signature, and copy a request or verification example. Everything runs locally in your browser.

Sample eventReceiver URL

Signing secretExact raw JSON bodyX-Zippy-Signature

Send and verify

cURL sends the generated sample. Other tabs show receiver-side verification using standard language libraries.

Verify Zippy Webhook

curl -X POST "https://merchant.example.com/webhooks/zippy" \
  -H "Content-Type: application/json" \
  -H "X-Zippy-Signature: sha256=GENERATE_SIGNATURE_FIRST" \
  -H "X-Zippy-Delivery-Id: delivery_test_001" \
  --data '{
  "id": "11111111-1111-4111-8111-111111111111",
  "type": "inquiry.approved",
  "createdAt": "2026-01-15T10:30:00.000Z",
  "data": {
    "inquiryId": "96b1f81d-87cd-4a71-8bc4-e2718bcd6097",
    "referenceId": "order_1001",
    "status": "APPROVED",
    "approvedAt": "2026-01-15T10:30:00.000Z",
    "correlationId": "33333333-3333-4333-8333-333333333333",
    "succeededCapabilities": [
      "PERSONAL_INFO",
      "PASSPORT_SCAN",
      "FACE_MATCH"
    ]
  }
}'

Common failures

Framework parsed JSON and re-serialized with different key order/spacing.
Comparing the full header including sha256= to a bare hex digest.
Using the wrong secret after endpoint rotation/recreate.

Webhook event catalog

Webhook deliveries