Webhooks Overview

What is a webhook

Webhooks let your system receive real-time event notifications from Yuno through an HTTP POST, instead of polling for updates. After you configure your webhook endpoint, Yuno sends a notification every time a relevant event happens in the payment flow.

Requirements

To use Yuno’s webhooks, build a public REST API endpoint to receive event notifications (POST requests). This endpoint should not require authentication or access restrictions through a header. Despite being public, the endpoint stays secure: Yuno’s event notifications aren’t discoverable by the public and are sent to a unique URL known only to your system.

Webhooks delivery and response requirements

Yuno webhooks expects to receive an HTTP 200 OK status as a response to confirm the webhook was successfully received. The merchant system does not need to include any information in the response’s body. Only the HTTP 200 status is required. If no response is received within the specified time, Yuno will retry sending the event notification up to seven times. Refer to the Receipt Confirmation Process section for details on the notification schedule and confirmation waiting times for each retry.

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

Every event payload includes 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.

Coverage

data.idempotency_key is currently included in:

payment events
refund events
chargeback events
subscription events

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 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 data.idempotency_key, incremented retry) following the schedule described in Webhooks delivery and response requirements above. Treat any event whose type_event and idempotency key you’ve already processed as a duplicate, regardless of its retry value.

Recommended handling

Store every data.idempotency_key you’ve successfully processed together with the event’s type_event, and check incoming events against that store before acting on them:

async function handleWebhookEvent(event) {
  // Scope the key by event type: a subscription's key is the same on every
  // one of its lifecycle events.
  const key = `${event.type_event}:${event.data.idempotency_key}`;

  if (await store.has(key)) {
    // Already processed, acknowledge and skip.
    return;
  }

  await processEvent(event);
  await store.add(key);
}

Keep in mind that not every event type carries data.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.

Common Webhook Events

Yuno sends event notifications for various activities within the payment ecosystem. Below are the available event categories and their corresponding events.

Payment events

Event	Description
`payment.purchase`	Occurs when a payment is created or its status changes during a purchase flow.
`payment.chargeback`	Occurs when a chargeback or inquiry is received for a payment.

Refund events

Event	Description
`payment.refund`	Occurs when a refund is processed for a payment.

Subscription events

Event	Description
`subscription.create`	Sent when a subscription is first created.
`subscription.active`	Sent when the subscription first becomes active (at `billing_cycles.current` = 2). Not re-sent on subsequent renewal cycles, but it is sent again when a subscription recovers from `PAST_DUE` back to `ACTIVE`.
`subscription.trialing`	Sent when the subscription enters a plan’s trial phase from another status, and when it recovers from `PAST_DUE` while the trial is still running. Entering the trial on creation is reported as `subscription.create`, and leaving a pause as `subscription.resume`.
`subscription.past_due`	Sent when a recurring charge fails and the subscription enters `PAST_DUE`. Only emitted for accounts where the status is enabled. See Subscription Status.
`subscription.pause`	Sent when a subscription is paused.
`subscription.resume`	Sent when a paused subscription is resumed.
`subscription.cancel`	Sent when a subscription is canceled. Once canceled it is terminated and cannot be reactivated.
`subscription.complete`	Sent when a subscription reaches its end date or total billing cycles and transitions to `COMPLETED`.
`subscription.close_to_renewal`	Sent ahead of an upcoming renewal. Timing is controlled by `renewal_notification_days`.
`subscription.cycle_executed`	Sent for plan-based subscriptions when a `$0` cycle is executed — a trial cycle or a fully discounted one. These cycles produce no `payment.purchase` webhook, so this event is the receipt for them. Carries `cycle`, `reason` (`TRIAL` or `FULL_DISCOUNT`), `phase` and a `breakdown`.
`subscription.phase_started`	Sent for plan-based subscriptions when a new billing phase begins, including the first one. Carries `phase` and `previous_phase`.
`subscription.phase_completed`	Sent for plan-based subscriptions when the previous billing phase ends, immediately before `subscription.phase_started` for the new one. Not sent for the first phase, which has no predecessor.
`subscription.plan_change_scheduled`	Sent when a plan change is scheduled for the next billing cycle via `PATCH /v1/subscriptions/{id}`.
`subscription.plan_change_canceled`	Sent when a pending plan change is undone by the merchant (`MERCHANT_UNDO`) or aborted because the target plan was canceled (`TARGET_PLAN_CANCELED`). Not sent when the subscription itself is canceled — only `subscription.cancel` fires then.
`subscription.plan_changed`	Sent when a plan change takes effect. A scheduled change is applied at the renewal that first bills the new plan and keeps the same subscription `code`. `POST /v1/subscriptions/{id}/plan` instead replaces the subscription: the payload carries a new `code` with `previous_subscription_id` set, and a separate `subscription.cancel` (`cancellation_source: PLAN_CHANGE`) fires for the original.

Each renewal charge is delivered as a payment.purchase webhook tied to the subscription, with the outcome (success or decline) carried in the status/sub_status fields. $0/trial cycles emit no payment webhook — for plan-based subscriptions they are reported as subscription.cycle_executed instead. There is no subscription.error event: a failed renewal is signaled by subscription.past_due where that status is enabled, and by the payment.purchase webhook everywhere.

Treat the plan-change events as notifications, not as the source of truth. Reconcile against GET /v1/subscriptions/{id} — pending_plan_change for a scheduled change and plan_id for an applied one — rather than relying on webhook delivery alone.

Enrollment events

Event	Description
`enrollment.enroll`	Sent when a payment method is successfully enrolled.
`enrollment.update`	Sent when enrolled card details are updated (e.g., via Card Account Updater).

Payout events

Event	Description
`payout.payout`	Sent when a payout event occurs.

Marketplace Split Transfer events

Event	Description
`succeeded` (Type: `split_transfer`)	Split transfer completed successfully
`succeeded` (Type: `split_transfer_reverse`)	Split transfer reversal completed successfully

Banking Connectivity webhook events

Banking Connectivity (Banking as a Service) webhook notifications follow the same delivery and retry behavior described above. Yuno sends these events to your configured webhook endpoint when the status of a Banking Connectivity resource changes. For incoming transfer payload structure, see Webhook Notifications (Banking Connectivity). Incoming transfer notifications are sent to your endpoint at {merchant_base_URL}/v1/banking/transfers.

Entity events

Event	Description
`banking.entity.created`	Entity created
`banking.entity.updated`	Entity updated
`banking.entity.deleted`	Entity deleted

Onboarding events

Event	Description
`banking.onboarding.created`	Onboarding created
`banking.onboarding.pending`	Submitted, awaiting review
`banking.onboarding.pending_additional_documentation`	More documents required
`banking.onboarding.succeeded`	Onboarding approved
`banking.onboarding.failed`	Onboarding failed
`banking.onboarding.declined`	Provider declined
`banking.onboarding.cancelled`	Merchant cancelled
`banking.onboarding.expired`	Onboarding expired

Account events

Event	Description
`banking.account.created`	Account created
`banking.account.updated`	Account updated
`banking.account.activated`	Account activated
`banking.account.closed`	Account closed

Transfer events (outgoing)

Event	Description
`banking.transfer.pending`	Transfer pending
`banking.transfer.processing`	Transfer processing
`banking.transfer.completed`	Transfer completed
`banking.transfer.failed`	Transfer failed
`banking.transfer.cancelled`	Transfer cancelled
`banking.transfer.reversed`	Transfer reversed

Transfer events (incoming)

Event	Description
`banking.transfer.incoming.pending`	Incoming transfer pending settlement
`banking.transfer.incoming.completed`	Incoming transfer settled

Getting Started

Core Concepts

Using Yuno

Direct Integration Use Cases

Payment Features

Payouts and Disputes

Webhooks

Wallets

AI Capabilities

Security and Compliance

Plugins

Additional Services

What is a webhook

Requirements

Webhooks delivery and response requirements

De-duplication

The identifier

Coverage

Why you might see the same event twice

Recommended handling

Common Webhook Events

Payment events

Refund events

Subscription events

Enrollment events

Payout events

Marketplace Split Transfer events

Banking Connectivity webhook events

Entity events

Onboarding events

Account events

Transfer events (outgoing)

Transfer events (incoming)

​What is a webhook

​Requirements

​Webhooks delivery and response requirements

​De-duplication

​The identifier

​Coverage

​Why you might see the same event twice

​Recommended handling

​Common Webhook Events

​Payment events

​Refund events

​Subscription events

​Enrollment events

​Payout events

​Marketplace Split Transfer events

​Banking Connectivity webhook events

​Entity events

​Onboarding events

​Account events

​Transfer events (outgoing)

​Transfer events (incoming)

What is a webhook

Requirements

Webhooks delivery and response requirements

De-duplication

The identifier

Coverage

Why you might see the same event twice

Recommended handling

Common Webhook Events

Payment events

Refund events

Subscription events

Enrollment events

Payout events

Marketplace Split Transfer events

Banking Connectivity webhook events

Entity events

Onboarding events

Account events

Transfer events (outgoing)

Transfer events (incoming)