Webhook - Handling best practices

​

Use the SDK built-in WebhookHandler

• 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.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);
});

​

Handle final state, not delivery order

• Do not update final business state based only on callback arrival order
• Deduplicate by subscriptionId, event ID, or your business order ID
• If you subscribe to both SUBSCRIPTION_STATUS_NOTIFICATION and SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION, call POST /api/v1/subscription/inquiry after receiving either callback, then run one unified subscription callback flow based on the final inquiry result

​

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)