Webhook events

nuez sends a POST request to your configured endpoint for every transfer outcome.

Common envelope

Every webhook has the same outer structure:

{
  "id": "evt_01HXYZ...",
  "type": "transfer.completed",
  "created_at": "2026-04-23T14:32:02Z",
  "data": { ... }
}

transfer.completed

Transfer executed successfully on the rail.

{
  "id": "evt_01HXYZ...",
  "type": "transfer.completed",
  "created_at": "2026-04-23T14:32:02Z",
  "data": {
    "transfer_id": "txn_01HXYZ...",
    "amount": 5000,
    "destination": "proveedor.empresa",
    "description": "Invoice #42",
    "completed_at": "2026-04-23T14:32:02Z"
  }
}

transfer.failed

Transfer was rejected by the payment rail.

{
  "id": "evt_01HXYZ...",
  "type": "transfer.failed",
  "created_at": "2026-04-23T14:32:02Z",
  "data": {
    "transfer_id": "txn_01HXYZ...",
    "amount": 5000,
    "destination": "invalid.alias",
    "reason": "invalid_destination"
  }
}

transfer.approved

Owner approved a pending transfer via WhatsApp.

{
  "id": "evt_01HXYZ...",
  "type": "transfer.approved",
  "created_at": "2026-04-23T14:33:15Z",
  "data": {
    "transfer_id": "txn_01HXYZ...",
    "amount": 50000,
    "destination": "proveedor.empresa",
    "approved_at": "2026-04-23T14:33:15Z"
  }
}

transfer.rejected

Owner rejected a pending transfer via WhatsApp.

{
  "id": "evt_01HXYZ...",
  "type": "transfer.rejected",
  "created_at": "2026-04-23T14:33:15Z",
  "data": {
    "transfer_id": "txn_01HXYZ...",
    "amount": 50000,
    "destination": "proveedor.empresa",
    "rejected_at": "2026-04-23T14:33:15Z"
  }
}

transfer.expired

Approval window timed out (5 minutes with no response).

{
  "id": "evt_01HXYZ...",
  "type": "transfer.expired",
  "created_at": "2026-04-23T14:37:00Z",
  "data": {
    "transfer_id": "txn_01HXYZ...",
    "amount": 50000,
    "expired_at": "2026-04-23T14:37:00Z"
  }
}