Skip to main content

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​

  1. Build an endpoint on your server that accepts POST requests with a JSON body.
  2. Send Nodu the URL of the endpoint and the list of event types that you want to receive.
  3. 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:

FieldMeaning
idThe unique identifier of the event, a UUID. It stays the same when Nodu delivers the event again.
typeThe event type, in the form v1.<resource>.<action>. For example, v1.transfer.payment_processed.
occurredAtThe time of the change, as an RFC 3339 timestamp.
A field named after the object, such as transfer or customerThe 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:

HeaderMeaning
svix-idThe identifier of the message. It stays the same when Nodu delivers the event again.
svix-timestampThe time of signing, in seconds since the Unix epoch.
svix-signatureOne or more signatures, separated by spaces. Each signature is a version, a comma and a base64 value: v1,<signature>.

To verify a request:

  1. 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.
  2. Remove the whsec_ prefix from the signing secret. Base64-decode the remaining text. The result is the key.
  3. Join the value of svix-id, the value of svix-timestamp and the raw body with periods: <svix-id>.<svix-timestamp>.<body>.
  4. Compute the HMAC-SHA256 of that text with the key. Base64-encode the result.
  5. Select the v1, entries of svix-signature and 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.
  6. Reject the request if svix-timestamp is 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:

  1. Store the event.
  2. Return 2xx.
  3. 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 id of each event that you process. Skip events whose id you 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 2xx for 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.

EventSent whenObject it carries
v1.transfer.createdA transfer is created.transfer
v1.transfer.awaiting_fundsA transfer enters awaiting_funds: Nodu is waiting to receive the funds.transfer
v1.transfer.in_reviewA transfer is paused for a compliance review.transfer
v1.transfer.info_requiredA transfer needs an action from the customer. The actions are listed in transfer.requirements.transfer
v1.transfer.funds_receivedNodu has received the funds and is preparing to process the transfer.transfer
v1.transfer.payment_submittedThe funds have been sent to the destination and are awaiting confirmation.transfer
v1.transfer.payment_processedThe transfer has completed and the funds have arrived at the destination.transfer
v1.transfer.undeliverableNodu could not complete the transfer, for example because the destination is not valid.transfer
v1.transfer.returnedThe transfer failed after it was submitted and the funds came back to Nodu. A refund to the payer is in progress.transfer
v1.transfer.refundedThe funds have been returned to the payer.transfer
v1.transfer.canceledThe transfer was canceled.transfer
v1.transfer.errorAn issue occurred that the transfer cannot recover from by itself. Nodu has to step in.transfer
v1.payment_channel.pendingA payment channel starts being set up for the customer.customer, paymentChannel
v1.payment_channel.activatedA payment channel becomes usable for the customer.customer, paymentChannel
v1.payment_channel.suspendedA payment channel can no longer be used by the customer.customer, paymentChannel
v1.customer.createdA customer is created.customer
v1.customer.tos_acceptedThe customer accepts Nodu's Terms of Service.customer
v1.customer.activatedThe customer's status becomes active.customer
v1.customer.suspendedThe customer's status becomes suspended.customer
v1.customer.blockedThe customer's status becomes blocked.customer
v1.customer.verification_under_reviewThe customer's verificationStatus becomes under_review: the information is submitted and awaits a decision.customer
v1.customer.verification_awaiting_associatesThe 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_approvedThe customer's verification is approved.customer
v1.customer.verification_resubmission_requiredThe customer's verification needs more information or a correction.customer
v1.customer.verification_permanently_rejectedThe customer's verification is permanently rejected.customer
v1.wallet.createdA Nodu wallet is created.wallet (without balances)
v1.wallet.activatedThe Nodu wallet's status becomes active.wallet (without balances)
v1.wallet.suspendedThe Nodu wallet's status becomes suspended.wallet (without balances)
v1.wallet.closedThe Nodu wallet's status becomes closed.wallet (without balances)
v1.relay.createdA relay is created.relay
v1.relay.activatedThe relay's status becomes active and its deposit instructions become available.relay

Next steps​