EN

Documentation

Events and webhooks

Every payment state change produces an event that reaches the owner's server by webhook and can be read for 30 days with GET /v1/events; the type list is open, so ignore the types you do not know.

How they are delivered

Webhooks are for the owner's server. The agent does not receive them: it checks the payment with GET /v1/spends/{id}.
Every event carries id, sequence (an increasing integer per environment), livemode and the API version. It is delivered at least once: deduplicate by id and drop any event whose sequence is lower than one already applied.
The signature travels in the Nouron-Signature header in the form t=<seconds>,v1=<hex>: an HMAC-SHA256 of the text <t>.<raw body> with the endpoint's whsec_… secret, with a tolerance of 300 seconds. During a rotation two v1 signatures arrive; one match is enough.
Answer 2xx as soon as you have read the delivery and process it afterwards. Otherwise it is retried 8 times over about 24 hours.
GET /v1/events is the backup: it keeps the last 30 days.

An event

{  "id": "evt_<32 hex>",  "object": "event",  "type": "spend.settled",  "api_version": "2026-10-01",  "created": "2026-10-09T14:03:24Z",  "livemode": false,  "sequence": 42,  "agent_id": "agt_<32 hex>",  "data": {    "object": {      "id": "spd_<32 hex>",      "object": "spend",      "status": "settled"    }  }}

The event types

Today there are 32 event types: 19 of the first phase, 11 for audit and 2 reserved.

The type list is open: new types can appear without changing the version. Ignore the ones you do not know and answer 2xx.

The types spend.created and approval.expired of the previous version no longer exist.

Payments

spend.pending_approval

The payment is waiting for the owner's approval (T2, T10).

object: spend · seen by: agent and owner · phase: first phase

spend.approved

It passed the rules; allowance reserved, not sent yet (T3, T4).

object: spend · seen by: agent and owner · phase: first phase

spend.declined

It was not paid: a rule, the owner or a change between steps (T1, T5, T6, T11).

object: spend · seen by: agent and owner · phase: first phase

spend.processing

It was sent to the rail; no result yet (T9).

object: spend · seen by: agent and owner · phase: first phase

spend.settled

Payment confirmed; the object carries settlement.receipt_id (T14).

object: spend · seen by: agent and owner · phase: first phase

spend.failed

It was approved and the rail rejected it; no money moved (T15).

object: spend · seen by: agent and owner · phase: first phase

spend.expired

The approval expired with no answer (T7, T12).

object: spend · seen by: agent and owner · phase: first phase

spend.cancelled

The agent cancelled before it was sent (T8, T13).

object: spend · seen by: agent and owner · phase: first phase

spend.refunded

Refund after settled (T17).

object: spend · seen by: agent and owner · phase: reserved

spend.disputed

A claim opened on a settled payment (T18).

object: spend · seen by: agent and owner · phase: reserved

Approvals

approval.requested

A pending approval was created for the owner.

object: approval · seen by: owner only · phase: first phase

approval.decided

The owner approved or rejected; carries the approver's channel and reference.

object: approval · seen by: owner only · phase: first phase

Funding

funding.awaiting_deposit

Waiting for a deposit into the practice pool.

object: funding · seen by: owner only · phase: first phase

funding.deposit_received

A deposit arrived.

object: funding · seen by: owner only · phase: first phase

funding.converted

A deposit was converted to practice digital dollars.

object: funding · seen by: owner only · phase: first phase

funding.failed

A deposit could not be completed.

object: funding · seen by: owner only · phase: first phase

Wallet

wallet.low_balance

The balance fell below the warning threshold.

object: wallet · seen by: owner only · phase: first phase

Rules

policy.updated

A new version of the rules was published; carries version and hash.

object: policy · seen by: agent and owner · phase: first phase

policy.change_requested

A change that LOOSENS rules was requested; it applies from effective_at unless cancelled.

object: policy_change · seen by: owner only · phase: audit

Agents

agent.paused

An agent was paused (the owner, the emergency pause or the platform).

object: agent · seen by: agent and owner · phase: first phase

agent.resumed

An agent was resumed.

object: agent · seen by: agent and owner · phase: first phase

agent.created

An agent was created.

object: agent · seen by: owner only · phase: audit

agent.archived

An agent was archived (its keys are revoked).

object: agent · seen by: owner only · phase: audit

Keys

api_key.created

An API key was created (never includes the secret).

object: api_key · seen by: owner only · phase: audit

api_key.rotated

A key was rotated; the old one lives on until grace_period_ends_at.

object: api_key · seen by: owner only · phase: audit

api_key.revoked

A key was revoked.

object: api_key · seen by: owner only · phase: audit

Destinations

destination.added

An allowed destination was added (it may have a wait before it applies).

object: destination · seen by: owner only · phase: audit

destination.removed

An allowed destination was removed.

object: destination · seen by: owner only · phase: audit

Notices

webhook_endpoint.created

A webhook endpoint was created.

object: webhook_endpoint · seen by: owner only · phase: audit

webhook_endpoint.paused

A webhook endpoint was paused after repeated failures.

object: webhook_endpoint · seen by: owner only · phase: audit

notification_channel.added

A notification channel (email, Telegram...) was added.

object: notification_channel · seen by: owner only · phase: audit

System

webhook.test

Test event sent at the owner's request; no subscription needed.

object: webhook_test · seen by: owner only · phase: first phase