Skip to main content

Webhook attributes

The JSON attributes for Yuno webhooks are listed below:
string
The unique identifier of the account in Yuno (MAX 64; MIN 36).
string
Specifies the notification type.
string
Specifies the event notification type.
string
Specifies the version of the webhook sent. Currently 2.
string
Specifies the number of retries for that notification.
object
Specifies the payment (for payment type) or payment method object (for enrollment and other objects).
string
Optional. The HMAC-SHA256 signature sent in the HTTP header for webhook verification when HMAC authentication is enabled.

Examples

Yuno provides several webhooks related to enrollment and payment notifications. Here you will find some examples of data structures related to each event.

Payment Webhook V2

Payment Webhook V1

Chargeback Webhook V2

Chargeback Webhook V1

Enrollment

Payouts

Subscriptions

Onboardings

Refunds

Marketplace Split Transfers

HMAC - Authorization

Payment

Payment Webhook V2

Example payload:
Webhook payloads for events corresponding to a bank transfer payment method include payment.payment_method.payment_method_detail.bank_transfer.bank_id. The field mirrors the bank_id sent in the original payment request and is omitted when no bank was selected.
Each transaction includes connection_data, which identifies the provider connection that processed it. Use connection_data.id as the stable identifier to attribute transactions to a specific connection when you operate multiple connections for the same provider. connection_data.name is the display name configured in the Yuno dashboard and can be null on some events, such as follow-up transactions.

Payment Webhook V1

Example payload:
JSON

Chargeback Webhook V2

Example payload:

Chargeback Webhook V1

Example payload:
JSON

Enrollment

Payouts

JSON

Subscriptions

JSON

subscription.active

Sent when a subscription transitions from any other valid status into ACTIVE. Use this event to trigger post-activation processes without polling.
JSON

subscription.trialing

Sent when a subscription enters a plan’s trial phase from another status. Entering the trial at creation time is reported as subscription.create, and leaving a pause into the trial as subscription.resume.
JSON

subscription.past_due

Sent when a recurring charge fails and the subscription enters PAST_DUE. The subscription keeps billing while the retries run and can still be canceled. When a later charge succeeds it returns to ACTIVE — or to TRIALING if the trial phase is still running — and the corresponding subscription.active or subscription.trialing event is sent. This event is only emitted for accounts where the PAST_DUE status is enabled. Where it is not, a failed charge leaves the subscription in ACTIVE and only the payment.purchase webhook reports the decline. See Subscription Status.
JSON

subscription.pause

Sent when a subscription is paused. Use this event to update the status in your system and pause related services.
JSON

subscription.resume

Sent when a paused subscription is resumed and transitions back to the ACTIVE status.
JSON

subscription.cancel

Sent when a subscription is canceled. Once canceled, the subscription is terminated and cannot be reactivated. The subscription object carries a cancellation_source field describing what triggered the cancellation — MERCHANT, SYSTEM, PLAN_CHANGE, or RETRIES_EXHAUSTED. See the subscription object for what each value means.
Treat cancellation_source as open-ended. New values can be added as Yuno introduces new cancellation behaviors, so handle an unrecognized value gracefully rather than switching exhaustively over the current list. RETRIES_EXHAUSTED is the most recent addition — it is sent when retries for a billing cycle end without a successful payment on a subscription created with retries.cancel_on_exhausted_retries set to true.
JSON

subscription.complete

Sent when a subscription reaches its end date or total billing cycles and transitions to the COMPLETED status.
JSON

subscription.close_to_renewal

Sent ahead of an upcoming renewal. Timing is controlled by renewal_notification_days on the subscription.
JSON

subscription.cycle_executed

Sent for plan-based subscriptions when a $0 cycle is executed, either a trial cycle or a fully discounted one. Those cycles produce no payment.purchase webhook, so this event is the only receipt for them. reason is TRIAL or FULL_DISCOUNT, phase is the phase the cycle belongs to, and breakdown carries the same line-item detail as a paid cycle, with a zero total.
JSON

subscription.phase_completed

Sent for plan-based subscriptions when a billing phase ends, immediately before the subscription.phase_started of the phase that replaces it. It is not sent for the first phase, which has no predecessor. phase is the phase that just ended.
JSON

subscription.phase_started

Sent for plan-based subscriptions when a billing phase begins, including the first one. phase is the phase that is starting and previous_phase is the one it replaces, or null for the first phase.
JSON

subscription.plan_change_scheduled

Sent when a plan change is scheduled for the next billing cycle. The plan_change block describes the pending change; applies_at is the next billing date the change will take effect on.
JSON

subscription.plan_change_canceled

Sent when a pending plan change is undone or aborted. The reason inside plan_change is MERCHANT_UNDO when the merchant sent "plan_change": null, or TARGET_PLAN_CANCELED when the target plan was canceled before the change applied — the subscription stays on its current plan in both cases. If the subscription itself is canceled, the pending change is silently discarded and only subscription.cancel is sent.
JSON

subscription.plan_changed

Sent when a plan change takes effect. previous_plan_id identifies the plan the subscription moved away from; the embedded subscription already reflects the new plan. A scheduled change is applied at the renewal that first bills the new plan, in place — the embedded subscription keeps the same 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.
JSON

Renewal charges and failures (no subscription.error)

There is no subscription.error webhook. Renewal-charge outcomes — successful rebills and failed/declined attempts — are delivered as payment.purchase webhooks tied to the subscription, with the result carried in the status/sub_status fields. Subscribe to payment.purchase to track renewal results. $0/trial cycles emit no payment webhook; on plan-based subscriptions they are reported as subscription.cycle_executed instead.
The renewal charge itself is always signaled by a payment.purchase webhook, never by a subscription webhook. The payments array inside the subscription object is currently always empty in webhook payloads. subscription.active is sent when the subscription first becomes active (at billing_cycles.current = 2), not on every renewal — it is sent again only when a subscription recovers from PAST_DUE.
A failed renewal does produce a subscription webhook in two cases. Where the PAST_DUE status is enabled for the account, the first failed charge of a cycle moves the subscription to PAST_DUE and emits subscription.past_due. And if the subscription has retries.cancel_on_exhausted_retries set to true, then once retries for that cycle end without a successful payment the subscription is canceled and a single subscription.cancel is emitted with cancellation_source set to RETRIES_EXHAUSTED. This is still not a subscription.error — the individual failed attempts remain payment.purchase webhooks. Only the final cancellation is signaled on the subscription.

Onboardings

Example

Marketplace Split Transfers

split_transfer.succeeded

split_transfer_reverse.succeeded

Refunds

Example

HMAC - Authorization