Responding to Webhook Requests

This section explains how your system should handle incoming webhook requests from Apara Checkout.

Successful Acknowledgment

• A webhook delivery is considered successful when your endpoint responds with an HTTP status code in the 2xx range (for example, 200 OK).
• Your system should validate the webhook payload before acknowledging the request.
• Return a 2xx response immediately after successfully receiving and validating the payload.
• Process the webhook within a reasonable time to avoid request timeouts.

Failed Deliveries

• Any response outside the 2xx range will be treated as a failed webhook delivery.
• Network failures or timeouts may also result in a failed delivery attempt.
• Apara may retry failed webhook deliveries based on the configured retry policy.

Best Practices

1. Process Asynchronously

Process webhook events asynchronously for long-running operations.

app.post('/webhook', (req, res) => {
  res.sendStatus(200);           // Acknowledge first
  processWebhookAsync(req.body); // Handle in background
});

2. Implement Idempotency

Implement idempotent webhook handling to safely process duplicate webhook events.

async function processWebhookAsync(payload) {
  const alreadyProcessed = await db.events.findOne({ eventId: payload.eventId });
  if (alreadyProcessed) return;

  await db.events.insert({ eventId: payload.eventId });
  // handle event...
}

3. Log Everything

Log all incoming webhook requests and responses for monitoring and debugging.

4. Validate Signatures

Secure your webhook endpoint by validating incoming requests before processing. See Webhook Signature.