Webhooks

The conceptual model: one normalized webhook contract across every provider, even providers that do not support webhooks natively. Then jump into the guides for setup, signatures, and the full event catalog.

This page is the concept. For the practical recipes (registering an endpoint, verifying signatures in your language, testing locally, the full event catalog with payloads) jump straight to the Webhooks guides.

One contract across every provider

Yuno gives you a single, normalized webhook contract regardless of which provider actually processed the transaction. Same envelope. Same event-name pattern. Same signature scheme. Same retry policy. Your code never branches on provider.

Provider A native webhook  ─┐
Provider B native webhook  ─┼──>  Yuno normalizes  ──>  Single contract POSTed to your endpoint
Provider C polled by Yuno  ─┘

The polling case is the part most platforms get wrong. Some providers have no webhook capability at all and force their integrators to poll forever. Yuno does that polling on your behalf and emits a webhook to your endpoint as soon as the status changes. From your side, every method on every provider behaves the same way: the synchronous response gives you the initial state, and webhooks deliver the rest.

Why webhooks are the source of truth

Most payments do not finalize in the synchronous response. Pix, Boleto, OXXO, PSE, SPEI, SEPA, ACH, BNPL, redirect wallets, crypto, and any card flow that triggers a 3DS challenge all return PENDING first and settle later. The webhook is what tells your server the final outcome. See the per-method breakdown in Sync vs async finality.

Even on synchronous flows, webhooks remain the canonical record for your backend: a network glitch can hide the synchronous response, but the webhook will retry until you acknowledge it.

Delivery model

Yuno treats your endpoint as the eventually-consistent source of truth. The contract:

• At least once delivery. Any non-2xx response or timeout triggers a retry on a backoff schedule that spans hours. The exact timeout and schedule are tunable per organization.
• Idempotent on your side. The same logical event can be delivered more than once. Use the resource id inside data plus the event name (type.type_event) as your dedupe key.
• Retry counter on the envelope. Every delivery includes a retry field. retry: 0 is the first attempt, retry: 1 is the first retry, and so on.
• Exhaustion is visible. When retries are exhausted, the event is marked failed and surfaced in the Dashboard. You can re-trigger it manually.

The four things every webhook handler must do

These are non negotiable. The guides walk through how to do each one.

1. Respond fast. Return HTTP 200 immediately, then process the event asynchronously in your own queue.
2. Verify the signature. Yuno signs every delivery with HMAC-SHA256. Without verification, an attacker can post fake events to your endpoint. See Verify signatures.
3. Handle duplicates. Treat every delivery as potentially a replay. Idempotent processing is the only safe model.
4. Use HTTPS. HTTP endpoints are not accepted.

Where to go next

Webhook setup

Register an endpoint in the Dashboard, pick which events to subscribe to.

Full event catalog

Every event type and the exact payload shape for each one.

Verify signatures

HMAC verification with copy-paste examples in Node, Python, Go, Ruby, PHP, and Java.

Test locally

Tunnel production events to your development machine.

Register webhook (API)

Programmatic registration when you do not want to use the Dashboard.

Sync vs async finality

Which methods return PENDING and rely on webhooks for finality.