Skip to main content
Guide hub4 pages

A webhook is an HTTP POST request that Yuno sends to your URL as soon as an event happens, such as a payment authorized, a subscription renewed or a payout completed, so your backend does not poll. Your endpoint must be a public HTTPS URL that accepts the request and returns HTTP 200, and you check that each delivery came from Yuno with HMAC or OAuth2 authentication.

Start here: Configure webhooks

Guide Set a webhook’s endpoint, triggers and delivery authentication from the dashboard or the API.

01 Build

Events and triggers

Reference Every event a webhook can subscribe to, by domain, and the trigger field that selects it.

Payloads and examples

Reference Payload attributes with example JSON for payments, chargebacks, enrollments, payouts and subscriptions.

Verify webhook signatures (HMAC)

Guide Validate the HMAC SHA256 signature header before you act on a delivery.

02 Operate

Delivery and retries

Reference The retry schedule Yuno follows when your endpoint does not return HTTP 200.

De-duplication

Guide The idempotency key per event type and the code that skips duplicate deliveries.

Split update notifications

Reference When a payment.split_update event fires and which fields to reconcile on.

Reference Create webhook List webhooks Update webhook

Delivery and retries

Yuno expects an HTTP 200 OK response to confirm a notification was received. No response body is required. If it doesn’t get one in time, Yuno retries on the schedule below, so a brief outage on your end doesn’t lose an event. Each retry delay counts from the previous attempt, and the elapsed time is approximate and counts from the first send.

De-duplication

Because Yuno retries delivery when it doesn’t receive a confirmation, your endpoint can receive the same event more than once. This is expected behavior, not a bug: your integration should be able to identify and skip duplicates.

The identifier

For ordinary v2 payment events, the key is data.payment.idempotency_key; for subscription events, it is data.idempotency_key. It stays stable across every retry of the same event, so you can use it to tell a duplicate delivery apart from a genuinely new event. For payment.split_update, use data.split_update.idempotency_key instead: it identifies the split update operation. The payment’s existing data.payment.idempotency_key can be shared by several different split updates. Scope your de-duplication record by account, event type, and operation key. In legacy v1 payloads, use the top-level split_update.idempotency_key.

Coverage

The key location depends on the event:
  • Ordinary payment events, including refund and chargeback: data.payment.idempotency_key
  • Split update events: data.split_update.idempotency_key
  • Subscription events: data.idempotency_key
For subscription.* events the key identifies the subscription, not the event: it is the X-Idempotency-Key sent when the subscription was created, and it is repeated identically on every lifecycle event for that subscription. De-duplicate subscription.* events on type_event plus data.idempotency_key — matching on the key alone collapses every event for a subscription into one and silently drops subscription.active, subscription.cancel and the rest.
Support for enrollment events is planned but not yet available. Until then, enrollment payloads do not include data.idempotency_key.

Why you might see the same event twice

Each v2 payload also includes a top-level retry field with the number of delivery attempts made for that event (0 on the first attempt). If your endpoint doesn’t return an HTTP 200 OK in time, Yuno resends the same event (same event-specific idempotency key, incremented retry) following the schedule described in Delivery and retries above. Treat any event whose type_event and idempotency key you’ve already processed as a duplicate, regardless of its retry value. For v2 payloads, store the event-specific key you’ve successfully processed together with the account and event’s type_event, and check incoming events against that store before acting on them:
Keep in mind that not every event type carries an idempotency key yet (see Coverage above). For event types without it, fall back to your own de-duplication key, such as the combination of resource ID and event type.

Configure a webhook

Webhooks are configured the same way whether you use the dashboard or the API. Both set the same url, triggers, and delivery authentication.

Configure a Webhook

Set up a webhook’s endpoint, triggers, and delivery authentication, from the dashboard or the API.

Split update notifications

payment.split_update requires the split-update trigger to be available in your account’s webhook catalog. Production subscription availability is pending; this event is not enabled by a purchase or refund subscription.
Subscribe explicitly to SPLIT_UPDATE in payment_triggers when the catalog makes it available. Existing PURCHASE and REFUND subscriptions and their payloads do not change. A notification is initiated after the split update is recorded as applied. It is also initiated after a manual resolution commits APPLY_REQUESTED (apply the requested split) or SET_EMPTY (clear the split). KEEP_PREVIOUS, failed or unresolved updates, same-key request replays, and repeated resolutions do not initiate another notification. The payload includes split_update.idempotency_key, the original split update request key, and split_update.updated_at, the recorded completion timestamp of that operation. This timestamp is not the webhook send time or the payment’s general update time. See the v1 and v2 examples. The event’s payment.transactions.split_marketplace is the split recorded for that operation. It remains that operation’s split even if a later update completes before delivery. Other payment fields are read when the notification is prepared, so the body is not a complete historical payment snapshot. For the latest state, retrieve the payment with GET /v1/payments/{payment_id}. Do not overwrite a newer split with an older event; use the operation timestamp when reconciling, and retrieve the payment when the order is ambiguous. Delivery is not exactly once and events may arrive out of order. The split update can succeed even if notification dispatch fails. Once a notification is accepted for webhook delivery, normal webhook retries can produce duplicate deliveries. De-duplicate by the split operation key, acknowledge receipt, and retrieve the payment when you need its current state.

What’s next

Events and Triggers

The full catalog of events you can subscribe to, by domain.

Payloads and Examples

Example JSON payloads for each event.

Verify Webhook Signatures (HMAC)

Confirm a notification genuinely came from Yuno and wasn’t tampered with.

Webhooks API Reference

Every field, endpoint, and error response for managing webhooks programmatically.