Webhooks

Nuntiq POSTs signed JSON events to a webhook's URL, so an integration does not have to poll. Webhooks are managed through the API (/v1/webhooks, permission MANAGE_WEBHOOKS) or by the customer in the customer portal (Integrations > Webhooks). A tenant has at most 20 webhooks. The URL must be https on a public address.

Events

Event	When
invoice.ready_for_integration	An invoice can be claimed (the ERP pull path of the workflow, a release, a confirmation)
invoice.integration_result	An integration result was recorded (API, portal, connector timeout, skip)
payment.applied	A payment and the invoices it pays
inbound_file.processed	A data file of POST /v1/inbound-files was consumed or failed
invoice.lifecycle_message	A lifecycle message (never the internal note)
supplier.bank_details_changed	A supplier's bank accounts changed (account numbers as their last four characters)
api_key.rotated	A key of an API user was created, rotated or revoked
api_key.expiring	A key expires in 30, 7 or 1 days

The list webhooks answer also gives the event types.

The request

Every event is one POST with a JSON body:

{
  "id": "b6f1...",
  "type": "api_key.expiring",
  "created_at": "2026-10-11T06:00:02.114Z",
  "data": { }
}

An event about one organization also carries organization_code. A webhook created by an organization-scoped key receives only the events of its organizations. Tenant-wide events, such as the api_key.* events, reach only webhooks without an organization limit.

Headers: X-Nuntiq-Event (the type), X-Nuntiq-Event-Id, X-Nuntiq-Delivery, X-Nuntiq-Timestamp and X-Nuntiq-Signature.

Verify the signature

X-Nuntiq-Signature: t=TIMESTAMP,v1=SIGNATURE. TIMESTAMP is in Unix seconds; SIGNATURE is the hex HMAC-SHA256 of TIMESTAMP.RAW_BODY with the webhook's signing secret (whsec_..., shown once when the webhook is created or its secret rotated). Compute it over the raw body, compare in constant time and reject old timestamps.

Delivery and retries

Answer with a 2xx status within 10 seconds. Nuntiq follows no redirects. Otherwise Nuntiq retries after 1, 5, 15 and 30 minutes, then hourly and every 4 hours, for 24 hours; then the delivery is failed. Deliveries are kept 30 days and can be replayed. Events can arrive twice or out of order: deduplicate on the event id and read the current state when order matters.

API key events

These follow the keys of the tenant's API users (see API keys and rotation). They never contain a key.

api_key.rotated, data:

Field	Meaning
action	created, rotated or revoked
api_user_id, api_user_name	The API user
key_id, key_label, key_prefix, key_last_4	The new key (created, rotated) or the revoked key
expires_at	When that key expires
via	portal (customer portal), admin (Nuntiq admin portal) or api (the integration itself)
replaced_key_id, replaced_key_prefix, replaced_key_grace_until	Rotation only: the old key and until when it still works

api_key.expiring, data: action (reminder_30, reminder_7 or reminder_1), days_left (30, 7 or 1), api_user_id, api_user_name, key_id, key_label, key_prefix, key_last_4, expires_at and via (system). Sent once per threshold, only for keys that are neither revoked nor replaced. When a key has expired, no event follows; the notification addresses get an email.