Skip to main content
A webhook tells Yuno where to send event notifications (url), which events to send (triggers), and how Yuno should authenticate to your endpoint when it delivers them. The same configuration is available from the Yuno dashboard. account_id is required on every request, in the body for POST and PATCH and as a query parameter for GET and DELETE. You can only manage the webhooks of the accounts in your own organization.

​
Secrets

Secrets are write-only. api_key, secret, hmac_client_secret and oauth2_client_secret are returned as *** once configured, and as null otherwise. To keep a secret as it is, omit it from the update. Sending the masked value back stores *** as the secret itself, and sending an empty string removes the secret.

​
Triggers

A webhook subscribes to events through five trigger fields, one per domain, and needs at least one trigger. A webhook with payment_triggers: ["AUTHORIZE"] is notified when a payment is authorized. See the event catalog for the events Yuno sends and Webhooks Examples for the payload each one carries.
FieldValues
enrollment_triggersENROLL, UNENROLL
payment_triggersAUTHORIZE, CANCEL, CAPTURE, CHARGEBACK, PRECHARGEBACK, PURCHASE, REFUND, VERIFY
report_triggersCREATE, UPDATE
subscription_triggersACTIVE, CANCEL, CLOSE_TO_RENEWAL, COMPLETE, CREATE, PAUSE, RESUME
onboarding_triggersBLOCKED, CANCELLED, CREATED, DECLINED, ERROR, EXPIRED, INACTIVE, PENDING, SUCCEEDED, TRANSFERRED, UNBLOCKED
Place each trigger in the field of its own domain: the field is what subscribes the webhook to that family of events. renewal_days sets how many days before a renewal Yuno sends the CLOSE_TO_RENEWAL notification, and is valid only when subscription_triggers contains CLOSE_TO_RENEWAL.

​
Delivery authentication

This is how Yuno authenticates to your endpoint when it sends an event, so your receiver can tell a genuine notification from a forged one. All the methods are optional and you can combine them.

​
API key and secret

Configure api_key and secret. Yuno sends them as headers on every delivery, and your endpoint checks that they match what you configured.

​
HMAC signature

Configure hmac_client_secret. Yuno signs the payload with it and sends the signature as a header, so you can verify that the notification is authentic and was not tampered with.
To verify it, compute the same HMAC over the raw body exactly as you received it, and compare the result with the header. Do not re-serialize the JSON first: a change in key order or whitespace produces a different signature. See Verify Webhook Signatures (HMAC).

​
OAuth2

Configure your token endpoint and your client credentials. Before delivering, Yuno requests a token from your endpoint and sends it as Authorization: Bearer <token>. Your token endpoint must use HTTPS. Yuno reuses a token across the deliveries of an account until it is close to expiring, so a short-lived token means a token request on almost every delivery.
FieldDescription
oauth2_authentication_urlYour token endpoint, over HTTPS.
oauth2_client_idThe client identifier Yuno authenticates with.
oauth2_client_secretThe client secret Yuno authenticates with.
oauth2_grant_typeThe grant type Yuno requests the token with, typically client_credentials.
oauth2_scopeThe scope Yuno requests the token with. Set it with Update a Webhook.
oauth2_authorization_nameThe header Yuno sends the token in. Defaults to Authorization.
oauth2_include_client_idSend the client identifier as a header on the token request as well.
Send oauth2_authentication_url, oauth2_client_id, oauth2_client_secret and oauth2_grant_type together: they are configured as a set.