> ## Documentation Index
> Fetch the complete documentation index at: https://docs.y.uno/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks Overview

> Explains how a webhook subscribes to events and how Yuno authenticates to your endpoint when it delivers them

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](/docs/webhooks/configure-webhooks).

`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](/docs/webhooks/configure-webhooks#webhooks-event-types) for the events Yuno sends and [Webhooks Examples](/docs/webhooks/object-and-examples) for the payload each one carries.

| Field                   | Values                                                                                                                            |
| :---------------------- | :-------------------------------------------------------------------------------------------------------------------------------- |
| `enrollment_triggers`   | `ENROLL`, `UNENROLL`                                                                                                              |
| `payment_triggers`      | `AUTHORIZE`, `CANCEL`, `CAPTURE`, `CHARGEBACK`, `PRECHARGEBACK`, `PURCHASE`, `REFUND`, `VERIFY`                                   |
| `report_triggers`       | `CREATE`, `UPDATE`                                                                                                                |
| `subscription_triggers` | `ACTIVE`, `CANCEL`, `CLOSE_TO_RENEWAL`, `COMPLETE`, `CREATE`, `PAUSE`, `RESUME`                                                   |
| `onboarding_triggers`   | `BLOCKED`, `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.

```
x-api-key: <api_key>
x-secret:  <secret>
```

### 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.

```
x-hmac-signature: Base64(
  HMAC-SHA256(key = hmac_client_secret, msg = <raw request body>)
)
```

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)](/docs/webhooks/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.

| Field                       | Description                                                                                                 |
| :-------------------------- | :---------------------------------------------------------------------------------------------------------- |
| `oauth2_authentication_url` | Your token endpoint, over HTTPS.                                                                            |
| `oauth2_client_id`          | The client identifier Yuno authenticates with.                                                              |
| `oauth2_client_secret`      | The client secret Yuno authenticates with.                                                                  |
| `oauth2_grant_type`         | The grant type Yuno requests the token with, typically `client_credentials`.                                |
| `oauth2_scope`              | The scope Yuno requests the token with. Set it with [Update a Webhook](/reference/webhooks/update-webhook). |
| `oauth2_authorization_name` | The header Yuno sends the token in. Defaults to `Authorization`.                                            |
| `oauth2_include_client_id`  | Send 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.