Skip to main content

​
Overview

Webhooks push events to your server in real-time. No polling needed. 
Event occurs in Waffo Pancake --> HTTP POST to your endpoint --> You process the event

​
Setup

1

Create an HTTPS Endpoint

Build a publicly accessible endpoint that accepts POST requests and returns 200 OK.
2

Register in Dashboard

Go to Dashboard > Developers > Webhooks. Add your endpoint URL.
3

Select Events

Choose which events to receive.
4

Save

Save your webhook configuration.

​
Event Types

Events cover payment, subscription, and refund lifecycle notifications. When configuring webhooks in the Dashboard, you can select which event categories to subscribe to.
The exact event names and available categories are shown in the Dashboard when you configure your webhook endpoint. Refer to your Dashboard for the current list.

​
Payload Format

Each webhook delivery is an HTTP POST with a JSON body containing the event type and associated data: 
{
  "event": "<event_type>",
  "data": {
    // Event-specific fields
  }
}
All IDs are UUID v4 format. Amounts are in the smallest currency unit (e.g., 2900 = $29.00). Timestamps are ISO 8601 UTC.

​
Handling Webhooks

Return 200 OK quickly. Process asynchronously if your handler needs to do heavy work. 
app.post('/webhooks/waffo', (req, res) => {
  // Respond immediately
  res.status(200).send('OK');

  // Process async
  const { event, data } = req.body;

  switch (event) {
    case 'payment.completed':
      handlePaymentCompleted(data);
      break;
    case 'subscription.created':
      handleSubscriptionCreated(data);
      break;
    case 'subscription.canceled':
      handleSubscriptionCanceled(data);
      break;
  }
});

​
Idempotency

Events may be delivered more than once. Use the event data for deduplication: 
const processedEvents = new Set();

app.post('/webhooks/waffo', (req, res) => {
  const { event, data } = req.body;
  const eventKey = `${event}:${data.id}`;

  if (processedEvents.has(eventKey)) {
    return res.status(200).send('Already processed');
  }

  processedEvents.add(eventKey);
  res.status(200).send('OK');
  processWebhook(event, data);
});
For production, store processed event IDs in a database instead of in-memory to persist across server restarts.

​
Retry Policy

Failed deliveries are retried automatically. Ensure your endpoint returns a 200 status code promptly to confirm receipt.

​
Testing

Use the Sandbox Environment to test webhooks:
  1. Switch to Test Mode in the Dashboard
  2. Go to Developers > Webhooks
  3. Perform actions that trigger events
  4. Check your endpoint for incoming events
Webhooks fire in both Test and Live modes. Make sure your endpoint can distinguish between environments.

​
Best Practices

  1. Use HTTPS — Required for production webhook endpoints
  2. Respond fast — Return 200 within 30 seconds
  3. Handle duplicates — Use IDs for deduplication
  4. Process async — Don’t block the response with heavy processing
  5. Log everything — Record incoming webhooks for debugging