Receive and verify webhooks
A webhook is an HTTP POST request that Nodu sends to your server when a customer, a transfer or another object changes state. Your endpoint verifies that Nodu sent it, acknowledges it, and handles repeated deliveries. Nodu retries a delivery that fails. The table at the end lists every event type.
Set up your endpoint
- Build an endpoint on your server that accepts
POSTrequests with a JSON body. - Send Nodu the URL of the endpoint and the list of event types that you want to receive.
- Nodu registers the endpoint. You receive the signing secret of the endpoint separately. Store the secret as carefully as an API key.
Ask only for the events that your integration acts on.
What a webhook contains
Every event has the same fields:
| Field | Meaning |
|---|---|
id | The unique identifier of the event, a UUID. It stays the same when Nodu delivers the event again. |
type | The event type, in the form v1.<resource>.<action>. For example, v1.transfer.payment_processed. |
occurredAt | The time of the change, as an RFC 3339 timestamp. |
A field named after the object, such as transfer or customer | The object snapshot at occurredAt; wallet events omit balances. |
An excerpt of a v1.transfer.payment_processed event, with most fields of transfer left out:
{
"id": "019657d0-caf7-7b5e-a0d2-8e9f0a1b2c3d",
"type": "v1.transfer.payment_processed",
"occurredAt": "2026-04-21T12:25:00+00:00",
"transfer": {
"id": "019634b8-f479-7001-84ce-2e15ced821e2",
"clientReferenceId": "client_transfer_id_123",
"customerId": "019634b8-f479-7001-84ce-2e15ced821e2",
"amount": "75",
"source": {"paymentRail": "base", "currency": "usdc"},
"destination": {
"paymentRail": "sepa",
"currency": "eur",
"externalAccountId": "019898a3-a741-7079-b676-5342179fc560"
},
"state": "payment_processed",
"updatedAt": "2026-04-21T12:25:00+00:00"
}
}
Except for wallet events, which omit balances, the object has the same fields as in an API response: transfer is the object that Retrieve a transfer returns. The reference shows a complete example of each event under Webhooks.
A webhook tells you what an object looked like at occurredAt, not what it looks like now. When you need the current state, retrieve the object through the API.
Verify the signature
Nodu signs every webhook. Verify the signature before you act on an event: anyone who knows your URL can send a request to it.
Each request carries three headers:
| Header | Meaning |
|---|---|
svix-id | The identifier of the message. It stays the same when Nodu delivers the event again. |
svix-timestamp | The time of signing, in seconds since the Unix epoch. |
svix-signature | One or more signatures, separated by spaces. Each signature is a version, a comma and a base64 value: v1,<signature>. |
To verify a request:
- Read the request body as raw bytes, before you parse the JSON. A body that was parsed and serialized again does not match the signature.
- Remove the
whsec_prefix from the signing secret. Base64-decode the remaining text. The result is the key. - Join the value of
svix-id, the value ofsvix-timestampand the raw body with periods:<svix-id>.<svix-timestamp>.<body>. - Compute the HMAC-SHA256 of that text with the key. Base64-encode the result.
- Select the
v1,entries ofsvix-signatureand compare their base64 values with your result using a constant-time function. Ignore unsupported signature versions. Reject the request if none matches. If one matches, continue to the timestamp check. - Reject the request if
svix-timestampis too far from the clock of your server. A tolerance of five minutes is a common choice. This check limits how long a captured request can be reused.
Accept the request only when both checks pass.
The Svix verification libraries are an optional resource for this signature format.
Acknowledge the event
Return any 2xx status promptly to tell Nodu that you received the event. Nodu treats every other response as a failed delivery: another status, a redirect (3xx), or a timeout.
We recommend acknowledging the event before doing slow work:
- Store the event.
- Return
2xx. - Process the event.
Retries
When a delivery fails, Nodu retries it. Retries are finite, so a successful receipt is not guaranteed. Keep the endpoint available and acknowledge promptly; do not use a presumed retry schedule as your recovery mechanism.
After your endpoint was unavailable, read the objects through the API to catch up with the changes that you missed: see Handle duplicates and order.
Handle duplicates and order
- Duplicates. Delivery attempts can repeat, so an event can arrive more than once. Successful receipt is not guaranteed after retries are exhausted. Record the
idof each event that you process. Skip events whoseidyou have already recorded. - Order. Events can arrive out of order, because Nodu sends a failed delivery again later. Do not let an older event overwrite newer data: compare
occurredAt, or retrieve the object. - Reconciliation. Do not depend on webhooks alone. Compare your records with the API from time to time, for example with List all transfers.
- Unknown types. Return
2xxfor an event type that you do not handle, so that Nodu does not send it again.
Event types
The Webhooks section of the API reference is the full reference: it describes every event and shows its complete payload. Each event name in the table links to its entry there.
| Event | Sent when | Object it carries |
|---|---|---|
v1.transfer.created | A transfer is created. | transfer |
v1.transfer.awaiting_funds | A transfer enters awaiting_funds: Nodu is waiting to receive the funds. | transfer |
v1.transfer.in_review | A transfer is paused for a compliance review. | transfer |
v1.transfer.info_required | A transfer needs an action from the customer. The actions are listed in transfer.requirements. | transfer |
v1.transfer.funds_received | Nodu has received the funds and is preparing to process the transfer. | transfer |
v1.transfer.payment_submitted | The funds have been sent to the destination and are awaiting confirmation. | transfer |
v1.transfer.payment_processed | The transfer has completed and the funds have arrived at the destination. | transfer |
v1.transfer.undeliverable | Nodu could not complete the transfer, for example because the destination is not valid. | transfer |
v1.transfer.returned | The transfer failed after it was submitted and the funds came back to Nodu. A refund to the payer is in progress. | transfer |
v1.transfer.refunded | The funds have been returned to the payer. | transfer |
v1.transfer.canceled | The transfer was canceled. | transfer |
v1.transfer.error | An issue occurred that the transfer cannot recover from by itself. Nodu has to step in. | transfer |
v1.payment_channel.pending | A payment channel starts being set up for the customer. | customer, paymentChannel |
v1.payment_channel.activated | A payment channel becomes usable for the customer. | customer, paymentChannel |
v1.payment_channel.suspended | A payment channel can no longer be used by the customer. | customer, paymentChannel |
v1.customer.created | A customer is created. | customer |
v1.customer.tos_accepted | The customer accepts Nodu's Terms of Service. | customer |
v1.customer.activated | The customer's status becomes active. | customer |
v1.customer.suspended | The customer's status becomes suspended. | customer |
v1.customer.blocked | The customer's status becomes blocked. | customer |
v1.customer.verification_under_review | The customer's verificationStatus becomes under_review: the information is submitted and awaits a decision. | customer |
v1.customer.verification_awaiting_associates | The verification status of a business becomes awaiting_associates: the business has submitted its application, and Nodu reviews it once its associates have completed their verification. | customer |
v1.customer.verification_approved | The customer's verification is approved. | customer |
v1.customer.verification_resubmission_required | The customer's verification needs more information or a correction. | customer |
v1.customer.verification_permanently_rejected | The customer's verification is permanently rejected. | customer |
v1.wallet.created | A Nodu wallet is created. | wallet (without balances) |
v1.wallet.activated | The Nodu wallet's status becomes active. | wallet (without balances) |
v1.wallet.suspended | The Nodu wallet's status becomes suspended. | wallet (without balances) |
v1.wallet.closed | The Nodu wallet's status becomes closed. | wallet (without balances) |
v1.relay.created | A relay is created. | relay |
v1.relay.activated | The relay's status becomes active and its deposit instructions become available. | relay |
Next steps
- Track and cancel a transfer: what each transfer state means and what you do.
- How onboarding works, and customer statuses: the statuses behind the customer events.
- Simulate funding in the sandbox: produce transfer events without real money.