Webhooks Overview

What is a webhook

Webhooks enable apps to provide real-time information whenever an event happens without needing constant requests. They are a passive method to receive data between two systems through an HTTP POST. After configuring the Yuno webhooks, you will receive event notifications every time an activity or a function is generated within the Yuno flow. Webhooks are the best way to ensure your system is up-to-date with payment progress and status. Since the event notifications trigger automatically, your system won’t need to perform recurrent requests to Yuno. You will process the payment information on demand.

What do you need to know before start using webhooks?

To start using Yuno’s webhooks, you need to build a public REST API to receive event notifications (POST request). That means the REST API you will build should not require any authentication or access restriction through a header. Despite using a public API, the communication system is very safe since Yuno event notifications will not be available to the public and will use a unique URL to communicate only to your REST API.

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 to ensure no information is lost. 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, a unique identifier for that event. 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

Support for enrollment events is landing on July 11, 2026. 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 carrying an 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, and check incoming events against that store before acting on them:

async function handleWebhookEvent(event) {
  const key = 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 once, when the subscription first becomes active (at `billing_cycles.current` = 2). Not re-sent on subsequent renewal cycles.
`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`.

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, and there is currently no subscription.error event.

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

What do you need to know before start using webhooks?

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

​Why do we recommend you use webhooks?

​What do you need to know before start using webhooks?

​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

Why do we recommend you use webhooks?

What do you need to know before start using webhooks?

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)