Skip to main content

Webhooks

WakaPay can POST events to your HTTPS endpoint when crypto checkout payments are created, paid, or expired. Configure webhook URLs per organisation in the dashboard.

Headers

Events: payment.created | payment.paid | payment.expired

Verify the signature

  1. Read the raw HTTP body bytes (do not re-serialize JSON)
  2. Concatenate X-Wakapay-Timestamp + "." + raw body
  3. HMAC-SHA256 with your organisation webhook secret
  4. Compare digests in constant time
  5. Reject if the timestamp is outside a ~5 minute window
Return 2xx when accepted. Return 4xx for bad signatures so WakaPay does not keep retrying a request that will never succeed. Failed deliveries retry with backoff.

Payload shape

Body is always { "event": "...", "data": { ... } }. Use data.email (and other fields in data) to reconcile against your own users.