Skip to main content

​
Response requirements

Your webhook endpoint must:
  • Respond within 30 seconds or the request will timeout
  • Return a 2xx status code (e.g., 200, 201, 204) to acknowledge successful receipt
  • Not perform long-running operations before responding
If your endpoint doesn’t respond with a 2xx status within 30 seconds, Nomos considers the delivery failed and will retry according to the exponential backoff schedule below.

​
Best practice: respond immediately

The recommended pattern is to:
  1. Verify the signature
  2. Store the event or queue it for processing
  3. Return a 2xx response immediately
  4. Process the event asynchronously
This ensures reliable delivery and prevents timeouts during processing.

​
Automatic retry strategy

If your endpoint returns a non-2xx status code or times out, Nomos automatically retries delivery with exponential backoff:
AttemptDelay
11 minute
22 minutes
34 minutes
48 minutes
516 minutes
632 minutes
71 hour
82 hours
94 hours
108 hours
1116 hours
1232 hours
Maximum attempts: 12 retries over approximately 3 days. Nomos stops retrying when your endpoint returns a successful 2xx response or after all retry attempts are exhausted.

​
Handling duplicate events

Due to retries and network conditions, your endpoint may occasionally receive the same event multiple times. Your implementation should be idempotent. Recommended approaches:
  • Store processed event IDs in a database and skip duplicates
  • Use the event ID as an idempotency key in your system
  • Design handlers that can safely process the same event multiple times

​
Event ordering

Nomos does not guarantee that events will be delivered in the order they were generated.
Your application might receive events out of order. For example, when creating a subscription you might receive:
  • subscription.confirmed before subscription.created
  • invoice.finalized before subscription.confirmed
How to handle ordering:
  • Design webhook handlers to process events independently
  • Use the timestamp field to determine event order if needed
  • Query the API for the current state of resources
  • Use event IDs to track which events you’ve processed