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.

​
Use the SDK built-in WebhookHandler

We strongly recommend using the SDK method webhook().handleWebhook(), which automatically handles:
  • Signature verification
  • JSON parsing and event routing
  • Response body construction and signing
const handler = waffo.webhook()
  .onPayment((n) => handlePayment(n))
  .onRefund((n) => handleRefund(n))
  .onSubscriptionStatus((n) => handleSubscription(n))
  .onSubscriptionChange((n) => handleChange(n));

app.post('/webhook', express.raw({ type: 'application/json' }), async (req, res) => {
  const result = await handler.handleWebhook(req.body.toString(), req.headers['x-signature'] as string);
  res.setHeader('X-SIGNATURE', result.responseSignature);
  res.status(200).send(result.responseBody);
});

​
Idempotent handling

Waffo may deliver the same event multiple times. Make sure your handling logic is idempotent: 
waffo.webhook().onPayment(async (notification) => {
  const orderId = notification.acquiringOrderId;

  const order = await db.order.findByAcquiringOrderId(orderId);
  if (order.status === 'PAY_SUCCESS') {
    return;
  }

  await updateOrderStatus(orderId, notification.orderStatus);
});

​
Fast responses

  • The SDK automatically builds the response after the handler finishes executing
  • Time-consuming operations (such as sending emails or updating external systems) should be handled asynchronously
  • If an exception is thrown in the handler, the SDK automatically returns a failure response

​
Security

  • Always verify X-SIGNATURE (handled automatically by the SDK)
  • Use an HTTPS endpoint
  • Verify the signature before processing the event—do not execute any business logic before verification passes
  • The response must include the X-SIGNATURE header (handled automatically by the SDK)