url, the events you want (triggers), and how Yuno authenticates to your endpoint. Yuno then delivers each event as an HTTP POST as soon as it happens.
To receive webhooks, your endpoint must be a public HTTPS URL that accepts an unauthenticated POST request. This is safe because the URL you configure is only ever called by Yuno, and you can verify every delivery is genuine with one of the authentication methods below.
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 up to seven times on the schedule below, so a brief outage on your end doesn’t lose an event.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 isdata.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
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-levelretry 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.
Recommended handling
For v2 payloads, store the event-specific key you’ve successfully processed together with the account and event’stype_event, and check incoming events against that store before acting on them:
Configure a webhook
Webhooks are configured the same way whether you use the dashboard or the API. Both set the sameurl, 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.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.