---
title: "Receive and verify webhooks"
description: "Set up an endpoint for Nodu webhooks, verify signatures, handle retries and repeated deliveries, and look up the event types."
url: "/guides/api-basics/webhooks/"
index: "/llms.txt"
---

# 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:

| 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:

```json
{
  "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](/api/tag/transfers/get-v1-transfers-transferid.md) returns. The reference shows a complete example of each event under [Webhooks](/api/tag/webhooks.md).

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:

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](https://docs.svix.com/receiving/verifying-payloads/how) 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).

## 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](/api/tag/transfers/get-v1-transfers.md).
- **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](/api/tag/webhooks.md) 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`](/api/tag/webhooks/webhook/POST/v1.transfer.created.md) | A transfer is created. | `transfer` |
| [`v1.transfer.awaiting_funds`](/api/tag/webhooks/webhook/POST/v1.transfer.awaiting-funds.md) | A transfer enters `awaiting_funds`: Nodu is waiting to receive the funds. | `transfer` |
| [`v1.transfer.in_review`](/api/tag/webhooks/webhook/POST/v1.transfer.in-review.md) | A transfer is paused for a compliance review. | `transfer` |
| [`v1.transfer.info_required`](/api/tag/webhooks/webhook/POST/v1.transfer.info-required.md) | A transfer needs an action from the customer. The actions are listed in `transfer.requirements`. | `transfer` |
| [`v1.transfer.funds_received`](/api/tag/webhooks/webhook/POST/v1.transfer.funds-received.md) | Nodu has received the funds and is preparing to process the transfer. | `transfer` |
| [`v1.transfer.payment_submitted`](/api/tag/webhooks/webhook/POST/v1.transfer.payment-submitted.md) | The funds have been sent to the destination and are awaiting confirmation. | `transfer` |
| [`v1.transfer.payment_processed`](/api/tag/webhooks/webhook/POST/v1.transfer.payment-processed.md) | The transfer has completed and the funds have arrived at the destination. | `transfer` |
| [`v1.transfer.undeliverable`](/api/tag/webhooks/webhook/POST/v1.transfer.undeliverable.md) | Nodu could not complete the transfer, for example because the destination is not valid. | `transfer` |
| [`v1.transfer.returned`](/api/tag/webhooks/webhook/POST/v1.transfer.returned.md) | 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`](/api/tag/webhooks/webhook/POST/v1.transfer.refunded.md) | The funds have been returned to the payer. | `transfer` |
| [`v1.transfer.canceled`](/api/tag/webhooks/webhook/POST/v1.transfer.canceled.md) | The transfer was canceled. | `transfer` |
| [`v1.transfer.error`](/api/tag/webhooks/webhook/POST/v1.transfer.error.md) | An issue occurred that the transfer cannot recover from by itself. Nodu has to step in. | `transfer` |
| [`v1.payment_channel.pending`](/api/tag/webhooks/webhook/POST/v1.payment-channel.pending.md) | A payment channel starts being set up for the customer. | `customer`, `paymentChannel` |
| [`v1.payment_channel.activated`](/api/tag/webhooks/webhook/POST/v1.payment-channel.activated.md) | A payment channel becomes usable for the customer. | `customer`, `paymentChannel` |
| [`v1.payment_channel.suspended`](/api/tag/webhooks/webhook/POST/v1.payment-channel.suspended.md) | A payment channel can no longer be used by the customer. | `customer`, `paymentChannel` |
| [`v1.customer.created`](/api/tag/webhooks/webhook/POST/v1.customer.created.md) | A customer is created. | `customer` |
| [`v1.customer.tos_accepted`](/api/tag/webhooks/webhook/POST/v1.customer.tos-accepted.md) | The customer accepts Nodu's Terms of Service. | `customer` |
| [`v1.customer.activated`](/api/tag/webhooks/webhook/POST/v1.customer.activated.md) | The customer's `status` becomes `active`. | `customer` |
| [`v1.customer.suspended`](/api/tag/webhooks/webhook/POST/v1.customer.suspended.md) | The customer's `status` becomes `suspended`. | `customer` |
| [`v1.customer.blocked`](/api/tag/webhooks/webhook/POST/v1.customer.blocked.md) | The customer's `status` becomes `blocked`. | `customer` |
| [`v1.customer.verification_under_review`](/api/tag/webhooks/webhook/POST/v1.customer.verification-under-review.md) | The customer's `verificationStatus` becomes `under_review`: the information is submitted and awaits a decision. | `customer` |
| [`v1.customer.verification_awaiting_associates`](/api/tag/webhooks/webhook/POST/v1.customer.verification-awaiting-associates.md) | 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`](/api/tag/webhooks/webhook/POST/v1.customer.verification-approved.md) | The customer's verification is approved. | `customer` |
| [`v1.customer.verification_resubmission_required`](/api/tag/webhooks/webhook/POST/v1.customer.verification-resubmission-required.md) | The customer's verification needs more information or a correction. | `customer` |
| [`v1.customer.verification_permanently_rejected`](/api/tag/webhooks/webhook/POST/v1.customer.verification-permanently-rejected.md) | The customer's verification is permanently rejected. | `customer` |
| [`v1.wallet.created`](/api/tag/webhooks/webhook/POST/v1.wallet.created.md) | A Nodu wallet is created. | `wallet` (without balances) |
| [`v1.wallet.activated`](/api/tag/webhooks/webhook/POST/v1.wallet.activated.md) | The Nodu wallet's `status` becomes `active`. | `wallet` (without balances) |
| [`v1.wallet.suspended`](/api/tag/webhooks/webhook/POST/v1.wallet.suspended.md) | The Nodu wallet's `status` becomes `suspended`. | `wallet` (without balances) |
| [`v1.wallet.closed`](/api/tag/webhooks/webhook/POST/v1.wallet.closed.md) | The Nodu wallet's `status` becomes `closed`. | `wallet` (without balances) |
| [`v1.relay.created`](/api/tag/webhooks/webhook/POST/v1.relay.created.md) | A relay is created. | `relay` |
| [`v1.relay.activated`](/api/tag/webhooks/webhook/POST/v1.relay.activated.md) | The relay's `status` becomes `active` and its deposit instructions become available. | `relay` |

## Next steps

- [Track and cancel a transfer](/guides/transfers/track-a-transfer/index.md): what each transfer state means and what you do.
- [How onboarding works, and customer statuses](/guides/customers/how-onboarding-works/index.md): the statuses behind the customer events.
- [Simulate funding in the sandbox](/guides/sandbox/simulate-funding/index.md): produce transfer events without real money.
