Sign in

v1

latestOpenAPI 3.0.02026-07-26167441.9 MB

Create a Webhook

Creates a webhook in active state, subscribed to the events you select. It requires at least one trigger, and starts receiving notifications immediately.

post/webhooks

Request body

account_idstring uuid required

The unique identifier of the account the webhook belongs to.

namestring required

Your name for the webhook. It must be unique within the account.

urlstring required

The endpoint Yuno sends the notifications to. It must be an http or https URL that resolves to a public, routable address.

api_keystring

Sent to your endpoint as the x-api-key header on every delivery.

secretstring

Sent to your endpoint as the x-secret header on every delivery.

hmac_client_secretstring

The key Yuno signs the payload with. The signature travels in the x-hmac-signature header.

oauth2_authentication_urlstring

Your token endpoint. It must use HTTPS. Send oauth2_authentication_url, oauth2_client_id, oauth2_client_secret and oauth2_grant_type together.

oauth2_client_idstring

The client identifier Yuno authenticates with. Send oauth2_authentication_url, oauth2_client_id, oauth2_client_secret and oauth2_grant_type together.

oauth2_client_secretstring

The client secret Yuno authenticates with. Send oauth2_authentication_url, oauth2_client_id, oauth2_client_secret and oauth2_grant_type together.

oauth2_grant_typestring

The grant type Yuno requests the token with. Send oauth2_authentication_url, oauth2_client_id, oauth2_client_secret and oauth2_grant_type together.

oauth2_authorization_namestring

The header Yuno sends the token in. Defaults to Authorization.

oauth2_include_client_idboolean

Send the client identifier as a header on the token request as well.

enrollment_triggersstring[]

The enrollment events the webhook subscribes to.

payment_triggersstring[]

The payment events the webhook subscribes to.

report_triggersstring[]

The report events the webhook subscribes to.

subscription_triggersstring[]

The subscription events the webhook subscribes to.

onboarding_triggersstring[]

The onboarding events the webhook subscribes to.

renewal_daysinteger

How many days before a renewal Yuno sends the CLOSE_TO_RENEWAL notification. It must be 1 or more, and it is valid only when subscription_triggers contains CLOSE_TO_RENEWAL.

Example request

{
  "account_id": "493e9374-510a-4201-9e09-de669d75f256",
  "name": "Production payments listener",
  "url": "https://api.acme.com/yuno/webhooks",
  "api_key": "my-webhook-key",
  "secret": "my-webhook-secret",
  "hmac_client_secret": "my-hmac-secret",
  "oauth2_authentication_url": "https://api.acme.com/oauth/token",
  "oauth2_client_id": "acme_client_id",
  "oauth2_client_secret": "acme_client_secret",
  "oauth2_grant_type": "client_credentials",
  "oauth2_authorization_name": "Authorization",
  "enrollment_triggers": [
    "ENROLL",
    "UNENROLL"
  ],
  "payment_triggers": [
    "AUTHORIZE",
    "CAPTURE",
    "REFUND"
  ],
  "report_triggers": [
    "UPDATE"
  ],
  "subscription_triggers": [
    "CREATE",
    "CLOSE_TO_RENEWAL"
  ],
  "onboarding_triggers": [
    "CREATED",
    "SUCCEEDED"
  ],
  "renewal_days": 5
}

Response

The webhook you created. The secrets you configured come back masked, and the ones you left out come back as null.

idstring

The unique identifier of the webhook.

account_idstring uuid

The unique identifier of the account the webhook belongs to.

namestring

Your name for the webhook.

state'ACTIVE' | 'INACTIVE'

ACTIVE webhooks receive notifications, INACTIVE ones do not. A webhook starts out ACTIVE.

urlstring

The endpoint Yuno sends the notifications to.

api_keystring

Masked as ***, or null when you have not configured it.

secretstring

Masked as ***, or null when you have not configured it.

hmac_client_secretstring

Masked as ***, or null when you have not configured it.

oauth2_authentication_urlstring

Your token endpoint.

oauth2_client_secretstring

Masked as ***, or null when you have not configured it.

oauth2_client_idstring

The client identifier Yuno authenticates with.

oauth2_grant_typestring

The grant type Yuno requests the token with.

oauth2_scopestring

The scope Yuno requests the token with.

oauth2_authorization_namestring

The header Yuno sends the token in.

oauth2_include_client_idboolean

Whether Yuno also sends the client identifier as a header on the token request.

enrollment_triggersstring[]

The enrollment events the webhook subscribes to.

payment_triggersstring[]

The payment events the webhook subscribes to.

report_triggersstring[]

The report events the webhook subscribes to.

subscription_triggersstring[]

The subscription events the webhook subscribes to.

onboarding_triggersstring[]

The onboarding events the webhook subscribes to.

{"stackTrail":"components:schemas:Webhook:properties:renewal_days","oasType":"schema","type":"unknown","description":"How many days before a renewal Yuno sends the `CLOSE_TO_RENEWAL` notification.","example":5}
created_atstring date-time

The date and time the webhook was created, in ISO 8601.

updated_atstring date-time

The date and time the webhook was last updated, in ISO 8601. It matches created_at until you update the webhook for the first time.

Example response

{
  "id": "12345",
  "account_id": "493e9374-510a-4201-9e09-de669d75f256",
  "name": "Production payments listener",
  "state": "ACTIVE",
  "url": "https://api.acme.com/yuno/webhooks",
  "api_key": "***",
  "secret": "***",
  "hmac_client_secret": "***",
  "oauth2_authentication_url": "https://api.acme.com/oauth/token",
  "oauth2_client_secret": "***",
  "oauth2_client_id": "acme_client_id",
  "oauth2_grant_type": "client_credentials",
  "oauth2_scope": "webhooks:write",
  "oauth2_authorization_name": "Authorization",
  "oauth2_include_client_id": true,
  "enrollment_triggers": [
    "ENROLL",
    "UNENROLL"
  ],
  "payment_triggers": [
    "AUTHORIZE",
    "CAPTURE",
    "REFUND"
  ],
  "report_triggers": [
    "UPDATE"
  ],
  "subscription_triggers": [
    "CREATE",
    "CLOSE_TO_RENEWAL"
  ],
  "onboarding_triggers": [
    "CREATED",
    "SUCCEEDED"
  ],
  "renewal_days": 5,
  "created_at": "2026-07-09T13:05:36.482913Z",
  "updated_at": "2026-07-11T16:20:44.918330Z"
}