Create a Webhook - Yuno API Documentation

POST

webhooks

Create a Webhook

curl --request POST \
  --url https://api-sandbox.y.uno/v1/webhooks \
  --header 'Content-Type: application/json' \
  --header 'private-secret-key: <api-key>' \
  --header 'public-api-key: <api-key>' \
  --data '
{
  "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",
  "enrollment_triggers": [
    "ENROLL",
    "UNENROLL"
  ],
  "payment_triggers": [
    "AUTHORIZE",
    "CAPTURE",
    "REFUND"
  ],
  "subscription_triggers": [
    "CREATE",
    "CLOSE_TO_RENEWAL"
  ],
  "renewal_days": 5
}
'

import requests

url = "https://api-sandbox.y.uno/v1/webhooks"

payload = {
    "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",
    "enrollment_triggers": ["ENROLL", "UNENROLL"],
    "payment_triggers": ["AUTHORIZE", "CAPTURE", "REFUND"],
    "subscription_triggers": ["CREATE", "CLOSE_TO_RENEWAL"],
    "renewal_days": 5
}
headers = {
    "public-api-key": "<api-key>",
    "private-secret-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'public-api-key': '<api-key>',
    'private-secret-key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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',
    enrollment_triggers: ['ENROLL', 'UNENROLL'],
    payment_triggers: ['AUTHORIZE', 'CAPTURE', 'REFUND'],
    subscription_triggers: ['CREATE', 'CLOSE_TO_RENEWAL'],
    renewal_days: 5
  })
};

fetch('https://api-sandbox.y.uno/v1/webhooks', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-sandbox.y.uno/v1/webhooks",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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',
    'enrollment_triggers' => [
        'ENROLL',
        'UNENROLL'
    ],
    'payment_triggers' => [
        'AUTHORIZE',
        'CAPTURE',
        'REFUND'
    ],
    'subscription_triggers' => [
        'CREATE',
        'CLOSE_TO_RENEWAL'
    ],
    'renewal_days' => 5
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "private-secret-key: <api-key>",
    "public-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api-sandbox.y.uno/v1/webhooks"

	payload := strings.NewReader("{\n  \"account_id\": \"493e9374-510a-4201-9e09-de669d75f256\",\n  \"name\": \"Production payments listener\",\n  \"url\": \"https://api.acme.com/yuno/webhooks\",\n  \"api_key\": \"my-webhook-key\",\n  \"secret\": \"my-webhook-secret\",\n  \"hmac_client_secret\": \"my-hmac-secret\",\n  \"enrollment_triggers\": [\n    \"ENROLL\",\n    \"UNENROLL\"\n  ],\n  \"payment_triggers\": [\n    \"AUTHORIZE\",\n    \"CAPTURE\",\n    \"REFUND\"\n  ],\n  \"subscription_triggers\": [\n    \"CREATE\",\n    \"CLOSE_TO_RENEWAL\"\n  ],\n  \"renewal_days\": 5\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("public-api-key", "<api-key>")
	req.Header.Add("private-secret-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api-sandbox.y.uno/v1/webhooks")
  .header("public-api-key", "<api-key>")
  .header("private-secret-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"account_id\": \"493e9374-510a-4201-9e09-de669d75f256\",\n  \"name\": \"Production payments listener\",\n  \"url\": \"https://api.acme.com/yuno/webhooks\",\n  \"api_key\": \"my-webhook-key\",\n  \"secret\": \"my-webhook-secret\",\n  \"hmac_client_secret\": \"my-hmac-secret\",\n  \"enrollment_triggers\": [\n    \"ENROLL\",\n    \"UNENROLL\"\n  ],\n  \"payment_triggers\": [\n    \"AUTHORIZE\",\n    \"CAPTURE\",\n    \"REFUND\"\n  ],\n  \"subscription_triggers\": [\n    \"CREATE\",\n    \"CLOSE_TO_RENEWAL\"\n  ],\n  \"renewal_days\": 5\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-sandbox.y.uno/v1/webhooks")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["public-api-key"] = '<api-key>'
request["private-secret-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"account_id\": \"493e9374-510a-4201-9e09-de669d75f256\",\n  \"name\": \"Production payments listener\",\n  \"url\": \"https://api.acme.com/yuno/webhooks\",\n  \"api_key\": \"my-webhook-key\",\n  \"secret\": \"my-webhook-secret\",\n  \"hmac_client_secret\": \"my-hmac-secret\",\n  \"enrollment_triggers\": [\n    \"ENROLL\",\n    \"UNENROLL\"\n  ],\n  \"payment_triggers\": [\n    \"AUTHORIZE\",\n    \"CAPTURE\",\n    \"REFUND\"\n  ],\n  \"subscription_triggers\": [\n    \"CREATE\",\n    \"CLOSE_TO_RENEWAL\"\n  ],\n  \"renewal_days\": 5\n}"

response = http.request(request)
puts response.read_body

{
  "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": null,
  "oauth2_client_secret": null,
  "oauth2_client_id": null,
  "oauth2_grant_type": null,
  "oauth2_scope": null,
  "oauth2_authorization_name": null,
  "oauth2_include_client_id": false,
  "enrollment_triggers": [
    "ENROLL",
    "UNENROLL"
  ],
  "payment_triggers": [
    "AUTHORIZE",
    "CAPTURE",
    "REFUND"
  ],
  "report_triggers": [],
  "subscription_triggers": [
    "CREATE",
    "CLOSE_TO_RENEWAL"
  ],
  "onboarding_triggers": null,
  "renewal_days": 5,
  "created_at": "2026-07-09T13:05:36.482913Z",
  "updated_at": "2026-07-09T13:05:36.482913Z"
}

Creates a webhook in ACTIVE state, so it starts receiving notifications immediately. Send the destination url, a name that is unique within the account, and at least one trigger. The response includes the id you use to retrieve, update and delete it. To secure how Yuno calls your endpoint, add the fields of any delivery authentication method to the same body. They are optional and you can combine them. The secrets you configure come back masked, and the rest come back as null.

To set oauth2_scope, use Update a Webhook.

An account can have several webhooks pointing at the same url, as long as they listen to different events. A webhook is rejected with 409 WEBHOOK_ALREADY_EXISTS when the account already has one with the same name, or one with the same url that listens to one of the same events.

Authorizations

public-api-key

string

header

default:<Your public-api-key>

required

private-secret-key

string

header

default:<Your private-secret-key>

required

Body

application/json

account_id

string<uuid>

required

The unique identifier of the account the webhook belongs to.

Example:

"493e9374-510a-4201-9e09-de669d75f256"

name

string

required

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

Example:

"Production payments listener"

url

string

required

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

Example:

"https://api.acme.com/yuno/webhooks"

api_key

string

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

Example:

"my-webhook-key"

secret

string

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

Example:

"my-webhook-secret"

hmac_client_secret

string

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

Example:

"my-hmac-secret"

oauth2_authentication_url

string

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

Example:

"https://api.acme.com/oauth/token"

oauth2_client_id

string

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

Example:

"acme_client_id"

oauth2_client_secret

string

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

Example:

"acme_client_secret"

oauth2_grant_type

string

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

Example:

"client_credentials"

oauth2_authorization_name

string

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

Example:

"Authorization"

oauth2_include_client_id

boolean

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

Example:

false

enrollment_triggers

enum<string>[]

The enrollment events the webhook subscribes to.

Available options:

ENROLL,

UNENROLL

Example:

["ENROLL", "UNENROLL"]

payment_triggers

enum<string>[]

The payment events the webhook subscribes to.

Available options:

AUTHORIZE,

CANCEL,

CAPTURE,

CHARGEBACK,

PRECHARGEBACK,

PURCHASE,

REFUND,

VERIFY

Example:

["AUTHORIZE", "CAPTURE", "REFUND"]

report_triggers

enum<string>[]

The report events the webhook subscribes to.

Available options:

CREATE,

UPDATE

Example:

["UPDATE"]

subscription_triggers

enum<string>[]

The subscription events the webhook subscribes to.

Available options:

ACTIVE,

CANCEL,

CLOSE_TO_RENEWAL,

COMPLETE,

CREATE,

PAUSE,

RESUME

Example:

["CREATE", "CLOSE_TO_RENEWAL"]

onboarding_triggers

enum<string>[]

The onboarding events the webhook subscribes to.

Available options:

BLOCKED,

CANCELLED,

CREATED,

DECLINED,

ERROR,

EXPIRED,

INACTIVE,

PENDING,

SUCCEEDED,

TRANSFERRED,

UNBLOCKED

Example:

["CREATED", "SUCCEEDED"]

renewal_days

integer

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:

5

Response

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

string

The unique identifier of the webhook.

Example:

"12345"

account_id

string<uuid>

The unique identifier of the account the webhook belongs to.

Example:

"493e9374-510a-4201-9e09-de669d75f256"

name

string

Your name for the webhook.

Example:

"Production payments listener"

state

enum<string>

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

Available options:

ACTIVE,

INACTIVE

Example:

"ACTIVE"

url

string

The endpoint Yuno sends the notifications to.

Example:

"https://api.acme.com/yuno/webhooks"

api_key

string | null

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

Example:

"***"

secret

string | null

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

Example:

"***"

hmac_client_secret

string | null

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

Example:

"***"

oauth2_authentication_url

string | null

Your token endpoint.

Example:

"https://api.acme.com/oauth/token"

oauth2_client_secret

string | null

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

Example:

"***"

oauth2_client_id

string | null

The client identifier Yuno authenticates with.

Example:

"acme_client_id"

oauth2_grant_type

string | null

The grant type Yuno requests the token with.

Example:

"client_credentials"

oauth2_scope

string | null

The scope Yuno requests the token with.

Example:

"webhooks:write"

oauth2_authorization_name

string | null

The header Yuno sends the token in.

Example:

"Authorization"

oauth2_include_client_id

boolean

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

Example:

true

enrollment_triggers

string[] | null

The enrollment events the webhook subscribes to.

Example:

["ENROLL", "UNENROLL"]

payment_triggers

string[] | null

The payment events the webhook subscribes to.

Example:

["AUTHORIZE", "CAPTURE", "REFUND"]

report_triggers

string[] | null

The report events the webhook subscribes to.

Example:

["UPDATE"]

subscription_triggers

string[] | null

The subscription events the webhook subscribes to.

Example:

["CREATE", "CLOSE_TO_RENEWAL"]

onboarding_triggers

string[] | null

The onboarding events the webhook subscribes to.

Example:

["CREATED", "SUCCEEDED"]

renewal_days

integer | null

How many days before a renewal Yuno sends the CLOSE_TO_RENEWAL notification.

Example:

5

created_at

string<date-time>

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

Example:

"2026-07-09T13:05:36.482913Z"

updated_at

string<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:

"2026-07-11T16:20:44.918330Z"

List WebhooksLists the webhooks configured on an account, optionally filtered by state

⌘I

Create a Webhook

curl --request POST \
  --url https://api-sandbox.y.uno/v1/webhooks \
  --header 'Content-Type: application/json' \
  --header 'private-secret-key: <api-key>' \
  --header 'public-api-key: <api-key>' \
  --data '
{
  "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",
  "enrollment_triggers": [
    "ENROLL",
    "UNENROLL"
  ],
  "payment_triggers": [
    "AUTHORIZE",
    "CAPTURE",
    "REFUND"
  ],
  "subscription_triggers": [
    "CREATE",
    "CLOSE_TO_RENEWAL"
  ],
  "renewal_days": 5
}
'

import requests

url = "https://api-sandbox.y.uno/v1/webhooks"

payload = {
    "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",
    "enrollment_triggers": ["ENROLL", "UNENROLL"],
    "payment_triggers": ["AUTHORIZE", "CAPTURE", "REFUND"],
    "subscription_triggers": ["CREATE", "CLOSE_TO_RENEWAL"],
    "renewal_days": 5
}
headers = {
    "public-api-key": "<api-key>",
    "private-secret-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'public-api-key': '<api-key>',
    'private-secret-key': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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',
    enrollment_triggers: ['ENROLL', 'UNENROLL'],
    payment_triggers: ['AUTHORIZE', 'CAPTURE', 'REFUND'],
    subscription_triggers: ['CREATE', 'CLOSE_TO_RENEWAL'],
    renewal_days: 5
  })
};

fetch('https://api-sandbox.y.uno/v1/webhooks', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-sandbox.y.uno/v1/webhooks",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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',
    'enrollment_triggers' => [
        'ENROLL',
        'UNENROLL'
    ],
    'payment_triggers' => [
        'AUTHORIZE',
        'CAPTURE',
        'REFUND'
    ],
    'subscription_triggers' => [
        'CREATE',
        'CLOSE_TO_RENEWAL'
    ],
    'renewal_days' => 5
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "private-secret-key: <api-key>",
    "public-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api-sandbox.y.uno/v1/webhooks"

	payload := strings.NewReader("{\n  \"account_id\": \"493e9374-510a-4201-9e09-de669d75f256\",\n  \"name\": \"Production payments listener\",\n  \"url\": \"https://api.acme.com/yuno/webhooks\",\n  \"api_key\": \"my-webhook-key\",\n  \"secret\": \"my-webhook-secret\",\n  \"hmac_client_secret\": \"my-hmac-secret\",\n  \"enrollment_triggers\": [\n    \"ENROLL\",\n    \"UNENROLL\"\n  ],\n  \"payment_triggers\": [\n    \"AUTHORIZE\",\n    \"CAPTURE\",\n    \"REFUND\"\n  ],\n  \"subscription_triggers\": [\n    \"CREATE\",\n    \"CLOSE_TO_RENEWAL\"\n  ],\n  \"renewal_days\": 5\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("public-api-key", "<api-key>")
	req.Header.Add("private-secret-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api-sandbox.y.uno/v1/webhooks")
  .header("public-api-key", "<api-key>")
  .header("private-secret-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"account_id\": \"493e9374-510a-4201-9e09-de669d75f256\",\n  \"name\": \"Production payments listener\",\n  \"url\": \"https://api.acme.com/yuno/webhooks\",\n  \"api_key\": \"my-webhook-key\",\n  \"secret\": \"my-webhook-secret\",\n  \"hmac_client_secret\": \"my-hmac-secret\",\n  \"enrollment_triggers\": [\n    \"ENROLL\",\n    \"UNENROLL\"\n  ],\n  \"payment_triggers\": [\n    \"AUTHORIZE\",\n    \"CAPTURE\",\n    \"REFUND\"\n  ],\n  \"subscription_triggers\": [\n    \"CREATE\",\n    \"CLOSE_TO_RENEWAL\"\n  ],\n  \"renewal_days\": 5\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-sandbox.y.uno/v1/webhooks")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["public-api-key"] = '<api-key>'
request["private-secret-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"account_id\": \"493e9374-510a-4201-9e09-de669d75f256\",\n  \"name\": \"Production payments listener\",\n  \"url\": \"https://api.acme.com/yuno/webhooks\",\n  \"api_key\": \"my-webhook-key\",\n  \"secret\": \"my-webhook-secret\",\n  \"hmac_client_secret\": \"my-hmac-secret\",\n  \"enrollment_triggers\": [\n    \"ENROLL\",\n    \"UNENROLL\"\n  ],\n  \"payment_triggers\": [\n    \"AUTHORIZE\",\n    \"CAPTURE\",\n    \"REFUND\"\n  ],\n  \"subscription_triggers\": [\n    \"CREATE\",\n    \"CLOSE_TO_RENEWAL\"\n  ],\n  \"renewal_days\": 5\n}"

response = http.request(request)
puts response.read_body

{
  "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": null,
  "oauth2_client_secret": null,
  "oauth2_client_id": null,
  "oauth2_grant_type": null,
  "oauth2_scope": null,
  "oauth2_authorization_name": null,
  "oauth2_include_client_id": false,
  "enrollment_triggers": [
    "ENROLL",
    "UNENROLL"
  ],
  "payment_triggers": [
    "AUTHORIZE",
    "CAPTURE",
    "REFUND"
  ],
  "report_triggers": [],
  "subscription_triggers": [
    "CREATE",
    "CLOSE_TO_RENEWAL"
  ],
  "onboarding_triggers": null,
  "renewal_days": 5,
  "created_at": "2026-07-09T13:05:36.482913Z",
  "updated_at": "2026-07-09T13:05:36.482913Z"
}