Skip to main content
Webhooks allow your application to receive real-time notifications when events happen in your Nomos account. When an event occurs, such as when a subscription is created or an invoice is finalized, Nomos sends an HTTPS POST request to your configured endpoint with details about the event.
Webhooks are essential for building reliable integrations that respond to asynchronous events. Rather than continuously polling for updates, webhooks push data to your application in real-time.

​
Overview

Webhooks enable you to:
  • React to events instantly: Get notified the moment something happens in your Nomos account
  • Reduce polling: No need to continuously check for updates via API calls
  • Build asynchronous workflows: Handle long-running processes without blocking user interactions

​
Getting started

  1. Set up an endpoint: Create an HTTPS endpoint in your application to receive webhook POST requests
  2. Register your endpoint: Access your dashboard to register your webhook URL and receive a webhook secret
  3. Verify signatures: Always validate incoming requests using the provided signature verification
  4. Process events: Handle the event data based on the topic field
  5. Respond quickly: Return a 2xx status code within 30 seconds

​
Security

​
Signature verification

Every webhook request includes an X-Nomos-Signature header containing an HMAC-SHA256 signature. Always verify this signature to ensure the request is authentic and from Nomos.
Never process webhook events without verifying the signature first. This protects against unauthorized requests and tampering.

​
Signature format

The signature header follows this format: 
t=1234567890,v1=3523dcc0013f08dfa1855772441107330218793f399d7452bd3ff2159c6e0285
Where:
  • t = Unix timestamp (seconds) when the webhook was sent
  • v1 = HMAC-SHA256 signature (hex-encoded)

​
How signatures are computed

Nomos generates signatures using HMAC-SHA256: 
HMAC-SHA256(timestamp + "." + JSON.stringify(payload), secret)
The signature is computed over:
  1. The timestamp (in seconds)
  2. A period (.) separator
  3. The JSON-stringified request body
This ensures both the timing and content of the webhook cannot be tampered with.

​
Preventing replay attacks

Nomos includes a timestamp in each webhook signature to prevent replay attacks. The timestamp is part of the signed payload, so attackers cannot modify it without invalidating the signature. Recommended tolerance: We recommend rejecting webhook signatures older than 5 minutes (based on the t value) When verifying signatures, you should set a tolerance window that protects against:
  • Old webhook events being replayed by attackers
  • Clock skew between servers
  • Network delays
You can adjust the tolerance window based on your security requirements, but never disable it entirely (setting it to 0) as this removes replay attack protection.

​
Event structure

All webhook events follow a consistent structure:
FieldTypeDescription
idstringUnique event identifier (starts with evt_)
timestampstringISO 8601 timestamp when the event was created
topicstringEvent type identifier (e.g., subscription.created)
contextobjectEvent-specific data containing relevant resource IDs
To support you with the concrete context values returned, refer to the events endpoint.

​
Event topics

Nomos currently supports the following webhook events:
Event TopicContext FieldsDescription
subscription.createdsubscription, lead (optional)A new subscription has been created
subscription.confirmedsubscriptionA subscription has been confirmed - can happen multiple times when the start date changes
All event topics follow the format resource.action (e.g., subscription.created, invoice.finalized). The context object contains IDs of relevant resources that you can use to fetch additional details via the API.

​
Response requirements

​
Timeout and expected response

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.

​
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.

​
Delivery and retries

​
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