Skip to main content
Follow these guidelines to build a robust webhook integration.

Respond quickly

Your webhook endpoint should return a 2xx status code as quickly as possible, ideally within 5 seconds. If your processing takes longer, acknowledge receipt first and process the data asynchronously.
// Good: acknowledge immediately, process later
app.post("/webhook", (req, res) => {
  res.status(200).send("OK"); // Respond immediately

  // Process asynchronously
  processWebhookAsync(req.body);
});

Implement idempotency

Numero may send the same webhook more than once (e.g., due to network issues or retries). Use the id field to detect duplicates:
const processedEvents = new Set(); // Use a database in production

app.post("/webhook", (req, res) => {
  const event = req.body;

  if (processedEvents.has(event.id)) {
    return res.status(200).send("Already processed");
  }

  processedEvents.add(event.id);
  // Process the event...

  res.status(200).send("OK");
});

Use HTTPS

Always use an HTTPS URL for your webhook endpoint. HTTP endpoints will not receive webhooks in production.

Verify signatures

Always verify the webhook signature in production. See Webhook Signature Verification for implementation examples.

Handle failures gracefully

If your endpoint is temporarily unavailable, Numero will retry delivery with exponential backoff for up to 24 hours. After 10 consecutive failures, the webhook subscription is automatically disabled. Make sure your endpoint can handle:
  • Delayed deliveries
  • Out-of-order events
  • Duplicate events

Rate limits

LimitValue
Webhook deliveries25 requests per second per account
Management API calls100 requests per minute per account

Need help?

Contact [email protected] for webhook-related support.