Webhook - Handling best practices

​

Use the SDK built-in WebhookHandler

• Signature verification
• JSON parsing and event routing
• Response body construction

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.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
• Choose an idempotency key for the event’s granularity, such as the event ID or your business order ID; combine subscriptionId and the period for period entitlements so that later periods are not skipped
• 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

​

Grant Subscription entitlements

• Check that the Subscription, period, and amount match the relevant plan and the amount due for that period
• Grant the corresponding entitlements only after the period’s payment succeeds and the checks pass
• Record entitlement grants by Subscription and period so that duplicate notifications do not grant them again
• When handling PAYMENT_NOTIFICATION, first use result.subscriptionInfo.subscriptionEvent to distinguish period charges, payment method additions, and top-ups. Do not use the latter two as the basis for granting a new period’s entitlements; see Subscription payment events

​

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