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.

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:

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

Need help?

Contact [email protected] for webhook-related support.