curl --request POST \
--url https://api.verbex.ai/v1/public/webhook/subscription \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "Payment Events Webhook",
"description": "Receives payment events with custom authentication",
"url": "https://api.example.com/webhooks/payments",
"active": true,
"enable_signed_webhooks": true,
"events": [],
"headers": {
"X-Custom-Header": "custom-value",
"Authorization": "Bearer your-api-token-here"
}
}
'import requests
url = "https://api.verbex.ai/v1/public/webhook/subscription"
payload = {
"name": "Payment Events Webhook",
"description": "Receives payment events with custom authentication",
"url": "https://api.example.com/webhooks/payments",
"active": True,
"enable_signed_webhooks": True,
"events": [],
"headers": {
"X-Custom-Header": "custom-value",
"Authorization": "Bearer your-api-token-here"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: 'Payment Events Webhook',
description: 'Receives payment events with custom authentication',
url: 'https://api.example.com/webhooks/payments',
active: true,
enable_signed_webhooks: true,
events: [],
headers: {'X-Custom-Header': 'custom-value', Authorization: 'Bearer your-api-token-here'}
})
};
fetch('https://api.verbex.ai/v1/public/webhook/subscription', 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.verbex.ai/v1/public/webhook/subscription",
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([
'name' => 'Payment Events Webhook',
'description' => 'Receives payment events with custom authentication',
'url' => 'https://api.example.com/webhooks/payments',
'active' => true,
'enable_signed_webhooks' => true,
'events' => [
],
'headers' => [
'X-Custom-Header' => 'custom-value',
'Authorization' => 'Bearer your-api-token-here'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$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.verbex.ai/v1/public/webhook/subscription"
payload := strings.NewReader("{\n \"name\": \"Payment Events Webhook\",\n \"description\": \"Receives payment events with custom authentication\",\n \"url\": \"https://api.example.com/webhooks/payments\",\n \"active\": true,\n \"enable_signed_webhooks\": true,\n \"events\": [],\n \"headers\": {\n \"X-Custom-Header\": \"custom-value\",\n \"Authorization\": \"Bearer your-api-token-here\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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.verbex.ai/v1/public/webhook/subscription")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"Payment Events Webhook\",\n \"description\": \"Receives payment events with custom authentication\",\n \"url\": \"https://api.example.com/webhooks/payments\",\n \"active\": true,\n \"enable_signed_webhooks\": true,\n \"events\": [],\n \"headers\": {\n \"X-Custom-Header\": \"custom-value\",\n \"Authorization\": \"Bearer your-api-token-here\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.verbex.ai/v1/public/webhook/subscription")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"Payment Events Webhook\",\n \"description\": \"Receives payment events with custom authentication\",\n \"url\": \"https://api.example.com/webhooks/payments\",\n \"active\": true,\n \"enable_signed_webhooks\": true,\n \"events\": [],\n \"headers\": {\n \"X-Custom-Header\": \"custom-value\",\n \"Authorization\": \"Bearer your-api-token-here\"\n }\n}"
response = http.request(request)
puts response.read_body{
"id": "6a27a76692d9e3a8ffd7e62d",
"organization_id": "ddd6f1d8-b232-497e-bf1e-ea7317622d17",
"scope": "ORGANIZATION",
"created_user_id": "google-oauth2|101090478854418701727",
"name": "Payment Events Webhook",
"url": "https://api.example.com/webhooks/payments",
"events": [],
"active": true,
"delivery_mode": "PUSH",
"headers": {
"X-Custom-Header": "custom-value",
"Authorization": "Bearer your-api-token-here"
},
"description": "Receives payment events with custom authentication",
"request_timeout_ms": 1000,
"retry_policy": {
"retryStrategy": "FIXED_DELAY",
"maxRetryAttempts": 3,
"maxRetryDelayMs": 10000
},
"signing_enabled": true,
"secret": "whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"created_at": "2026-06-09T10:15:00.000Z",
"updated_at": "2026-06-09T10:15:00.000Z"
}{
"status": 400,
"type": "VALIDATION_ERROR",
"message": "Validation failed",
"details": {},
"timestamp": "2023-11-07T05:31:56Z",
"path": "/v1/public/webhook/subscription",
"trace_id": "341b5325-a0be-4533-85dd-6f697476dfc3"
}{
"error": "Authentication",
"message": "Authentication failed",
"traceId": "e679120f-1d1c-41d2-947c-34e194d5a4a1"
}{
"status": 400,
"type": "VALIDATION_ERROR",
"message": "Validation failed",
"details": {},
"timestamp": "2023-11-07T05:31:56Z",
"path": "/v1/public/webhook/subscription",
"trace_id": "341b5325-a0be-4533-85dd-6f697476dfc3"
}{
"status": 400,
"type": "VALIDATION_ERROR",
"message": "Validation failed",
"details": {},
"timestamp": "2023-11-07T05:31:56Z",
"path": "/v1/public/webhook/subscription",
"trace_id": "341b5325-a0be-4533-85dd-6f697476dfc3"
}Create a subscription
Registers a new webhook subscription. With PUSH delivery (the default) Verbex sends selected event notifications to your url as HTTP POST requests; with PULL delivery events are stored for you to fetch. Optionally scope it to specific agents or workspaces, filter the events it receives, tune the timeout and retry policy, and enable HMAC-signed delivery. Returns the created subscription - including a one-time signing secret when enable_signed_webhooks is true. The secret (prefixed whsec_) is returned only once at creation, so store it securely; if it’s lost or leaked, rotate it via the rotate-secret endpoint.
curl --request POST \
--url https://api.verbex.ai/v1/public/webhook/subscription \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "Payment Events Webhook",
"description": "Receives payment events with custom authentication",
"url": "https://api.example.com/webhooks/payments",
"active": true,
"enable_signed_webhooks": true,
"events": [],
"headers": {
"X-Custom-Header": "custom-value",
"Authorization": "Bearer your-api-token-here"
}
}
'import requests
url = "https://api.verbex.ai/v1/public/webhook/subscription"
payload = {
"name": "Payment Events Webhook",
"description": "Receives payment events with custom authentication",
"url": "https://api.example.com/webhooks/payments",
"active": True,
"enable_signed_webhooks": True,
"events": [],
"headers": {
"X-Custom-Header": "custom-value",
"Authorization": "Bearer your-api-token-here"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: 'Payment Events Webhook',
description: 'Receives payment events with custom authentication',
url: 'https://api.example.com/webhooks/payments',
active: true,
enable_signed_webhooks: true,
events: [],
headers: {'X-Custom-Header': 'custom-value', Authorization: 'Bearer your-api-token-here'}
})
};
fetch('https://api.verbex.ai/v1/public/webhook/subscription', 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.verbex.ai/v1/public/webhook/subscription",
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([
'name' => 'Payment Events Webhook',
'description' => 'Receives payment events with custom authentication',
'url' => 'https://api.example.com/webhooks/payments',
'active' => true,
'enable_signed_webhooks' => true,
'events' => [
],
'headers' => [
'X-Custom-Header' => 'custom-value',
'Authorization' => 'Bearer your-api-token-here'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$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.verbex.ai/v1/public/webhook/subscription"
payload := strings.NewReader("{\n \"name\": \"Payment Events Webhook\",\n \"description\": \"Receives payment events with custom authentication\",\n \"url\": \"https://api.example.com/webhooks/payments\",\n \"active\": true,\n \"enable_signed_webhooks\": true,\n \"events\": [],\n \"headers\": {\n \"X-Custom-Header\": \"custom-value\",\n \"Authorization\": \"Bearer your-api-token-here\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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.verbex.ai/v1/public/webhook/subscription")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"Payment Events Webhook\",\n \"description\": \"Receives payment events with custom authentication\",\n \"url\": \"https://api.example.com/webhooks/payments\",\n \"active\": true,\n \"enable_signed_webhooks\": true,\n \"events\": [],\n \"headers\": {\n \"X-Custom-Header\": \"custom-value\",\n \"Authorization\": \"Bearer your-api-token-here\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.verbex.ai/v1/public/webhook/subscription")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"Payment Events Webhook\",\n \"description\": \"Receives payment events with custom authentication\",\n \"url\": \"https://api.example.com/webhooks/payments\",\n \"active\": true,\n \"enable_signed_webhooks\": true,\n \"events\": [],\n \"headers\": {\n \"X-Custom-Header\": \"custom-value\",\n \"Authorization\": \"Bearer your-api-token-here\"\n }\n}"
response = http.request(request)
puts response.read_body{
"id": "6a27a76692d9e3a8ffd7e62d",
"organization_id": "ddd6f1d8-b232-497e-bf1e-ea7317622d17",
"scope": "ORGANIZATION",
"created_user_id": "google-oauth2|101090478854418701727",
"name": "Payment Events Webhook",
"url": "https://api.example.com/webhooks/payments",
"events": [],
"active": true,
"delivery_mode": "PUSH",
"headers": {
"X-Custom-Header": "custom-value",
"Authorization": "Bearer your-api-token-here"
},
"description": "Receives payment events with custom authentication",
"request_timeout_ms": 1000,
"retry_policy": {
"retryStrategy": "FIXED_DELAY",
"maxRetryAttempts": 3,
"maxRetryDelayMs": 10000
},
"signing_enabled": true,
"secret": "whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"created_at": "2026-06-09T10:15:00.000Z",
"updated_at": "2026-06-09T10:15:00.000Z"
}{
"status": 400,
"type": "VALIDATION_ERROR",
"message": "Validation failed",
"details": {},
"timestamp": "2023-11-07T05:31:56Z",
"path": "/v1/public/webhook/subscription",
"trace_id": "341b5325-a0be-4533-85dd-6f697476dfc3"
}{
"error": "Authentication",
"message": "Authentication failed",
"traceId": "e679120f-1d1c-41d2-947c-34e194d5a4a1"
}{
"status": 400,
"type": "VALIDATION_ERROR",
"message": "Validation failed",
"details": {},
"timestamp": "2023-11-07T05:31:56Z",
"path": "/v1/public/webhook/subscription",
"trace_id": "341b5325-a0be-4533-85dd-6f697476dfc3"
}{
"status": 400,
"type": "VALIDATION_ERROR",
"message": "Validation failed",
"details": {},
"timestamp": "2023-11-07T05:31:56Z",
"path": "/v1/public/webhook/subscription",
"trace_id": "341b5325-a0be-4533-85dd-6f697476dfc3"
}Authorizations
Body
HMAC signing toggle for PUSH subscriptions. Optional: omitted means false (unsigned). On create, true generates a whsec_ signing secret returned once in the response. On update, true enables signing on an unsigned subscription (new secret returned once) and is a no-op when already signed; false disables signing and permanently clears the secret. Not supported for PULL (true returns 400).
true
Response
Created. Includes the one-time secret when signing is enabled.

