Skip to main content
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