Webhooks

Overview

nuez fires a POST to your configured endpoint whenever a tracked event happens — a payout changing state, an incoming deposit, a crypto off-ramp resolving. Webhooks are signed with HMAC-SHA256 (X-Nuez-Signature) so you can verify they came from nuez.

Events

Event	When it fires
`payout.requested`	A payout attempt was created (fires for both `allow` and `require_approval` outcomes)
`payout.submitted`	Payout was submitted to the bank rail
`payout.confirmed`	The bank rail confirmed the payout executed
`payout.approved`	Owner approved a pending payout via WhatsApp/Telegram
`payout.rejected`	Owner rejected a pending payout
`payout.expired`	Approval window timed out with no reply
`deposit.detected`	An incoming transfer to the user’s CVU was detected
`crypto.offramp.completed`	A crypto→ARS off-ramp finished
`crypto.offramp.failed`	A crypto→ARS off-ramp failed
`crypto.deposit.completed`	An incoming crypto deposit was detected

Full event payloads are documented in Webhook events.

Configuring your endpoint

Unlike API keys, there’s one webhook endpoint per user, not per key — configure it with:

curl -X PUT https://sandbox-api.nuez.app/v1/webhook \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/webhooks/nuez", "secret": "at-least-16-characters-long"}'

secret is required (minimum 16 characters) and is not generated by nuez — you choose it and use it to verify incoming signatures. See Endpoint reference.

Your endpoint must:

Accept POST requests
Return a 2xx status — nuez uses a 30-second request timeout

Delivery and retries

A background worker polls every 10 seconds for pending deliveries. On a non-2xx response or timeout, nuez retries with exponential backoff: 1 min → 5 min → 30 min → 2 hours, up to 5 attempts total, then gives up. Delivery records are pruned after 7 days.

Inspect delivery history (including failures) with GET /v1/webhook/deliveries.

Verifying signatures

Every webhook includes an X-Nuez-Signature: sha256=<hex> header, computed as HMAC-SHA256(secret, raw_body). See Webhook signatures for verification code in Go, Python, and TypeScript.