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": "payment_session.completed",
  "createdAt": "2026-08-31T12:00:00.000Z",
  "data": {
    "paymentSessionId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "COMPLETED",
    "merchantReference": "order-12345",
    "amount": "25.00",
    "currency": "USD",
    "transactionId": "880e8400-e29b-41d4-a716-446655440003",
    "transactionStatus": "COMPLETED",
    "payer": {
      "paymentId": "john.doe12",
      "displayName": "John S."
    }
  }
}'

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