Webhook

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

Requirement	Description
Protocol	HTTPS (TLS 1.2+)
Reachability	Accessible via the public internet
Signature	Waffo signs the request body using the Waffo private key; the merchant must verify `X-SIGNATURE` using the Waffo public key
Response signature	The 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"
  }
}

Response	Description
`success`	Successfully received and processed
`failed`	Processing failed; Waffo will retry
`unknown`	Status 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

⌘I

Getting Started

Core Concepts

Integration

SDK

Tools & Reference

Webhook - Overview and configuration

Why use Webhook

Configuration requirements

Webhook request structure

Merchant response

Configuration methods

Local development

​Why use Webhook

​Configuration requirements

​Webhook request structure

​Merchant response

​Configuration methods

​Local development

Why use Webhook

Configuration requirements

Webhook request structure

Merchant response

Configuration methods

Local development