Skip to main content

Documentation Index

Fetch the complete documentation index at: https://waffo.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Webhook is Waffo’s mechanism for pushing asynchronous event notifications to merchants. When the payment status changes, Waffo sends an HTTPS POST request to the merchant’s notifyUrl.

​
Why use Webhook

  • The authoritative source of payment results (higher priority than redirects and polling)
  • Asynchronous notifications that do not block the user flow
  • Covers all status change events

​
Configuration requirements

RequirementDescription
ProtocolHTTPS (TLS 1.2+)
ReachabilityAccessible via the public internet
SignatureWaffo signs the request body using the Waffo private key; the merchant must verify X-SIGNATURE using the Waffo public key
Response signatureThe merchant response must also be signed using the merchant private key
Response body{"message": "success"} / {"message": "failed"} / {"message": "unknown"}

​
Webhook request structure

{
  "header": {
    "Content-Type": "application/json",
    "X-SIGNATURE": "..."
  },
  "body": {
    "eventType": "PAYMENT_NOTIFICATION",
    "result": { ... }
  }
}

​
Merchant response

{
  "header": {
    "Content-Type": "application/json",
    "X-SIGNATURE": "..."
  },
  "body": {
    "message": "success"
  }
}
ResponseDescription
successSuccessfully received and processed
failedProcessing failed; Waffo will retry
unknownStatus unknown; Waffo will retry

​
Configuration methods

When creating an order/subscription, specify the callback URL via parameters:

​
Local development

Use an intranet tunneling tool to expose a local port as a public URL: 
# cloudflared
cloudflared tunnel --url http://localhost:3000

# ngrok
ngrok http 3000