Webhooks

Webhooks allow your application to receive asynchronous notifications when payments are successfully settled.

Do I need Webhooks?

• No, if you only need to gate a synchronous API response (e.g., return data immediately after payment). The SDK handles verification inline.
• Yes, if you need to:
  • Trigger a background job (e.g., generate a video, fine-tune a model).
  • Update a user's credit balance in your database.
  • Send a confirmation email.
  • Handle payments that might confirm slowly.

Setting up Webhooks

1. Register your Webhook URL in the Facilitator Dashboard (Coming Soon).
2. Listen for the payment.success event.

Payload Structure

{
  "event": "payment.success",
  "payload": {
    "settlementId": "stl_12345",
    "amount": "100000",
    "netAmount": "99000",
    "payer": "UserAddress...",
    "resource": "api-access"
  }
}

Security

Verify the webhook signature (HMAC) to ensure the request came from Zion. Documentation on signature verification coming soon.