Webhooks API
Create, list, read, update, and delete webhook endpoints via the API.
Webhooks API
Manage webhook endpoints programmatically. All endpoints require an API token with the settings.manage ability. For a conceptual overview of webhooks (events, HMAC signatures, retries), see the Webhooks article.
List Webhooks
GET /api/v1/webhooks — Permission: settings.manage
Example Request
curl -X GET "https://your-domain.com/api/v1/webhooks" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json"const response = await fetch("https://your-domain.com/api/v1/webhooks", {
headers: {
"Authorization": "Bearer YOUR_API_TOKEN",
"Accept": "application/json"
}
});
const data = await response.json();$ch = curl_init("https://your-domain.com/api/v1/webhooks");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer YOUR_API_TOKEN",
"Accept: application/json",
],
]);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);import requests
response = requests.get(
"https://your-domain.com/api/v1/webhooks",
headers={
"Authorization": "Bearer YOUR_API_TOKEN",
"Accept": "application/json"
}
)
data = response.json()Example Response
{
"data": [
{
"id": 1,
"url": "https://hooks.example.com/webhook",
"events": ["contact.created", "contact.updated"],
"config": null,
"status": "active",
"failure_count": 0,
"last_delivery_at": "2025-06-01T12:00:00.000000Z",
"disabled_at": null,
"created_at": "2025-03-10T10:00:00.000000Z",
"updated_at": "2025-06-01T12:00:00.000000Z"
}
],
"meta": { "current_page": 1, "last_page": 1, "per_page": 25, "total": 1 },
"links": { "first": "...", "last": "...", "prev": null, "next": null }
}Create Webhook
POST /api/v1/webhooks — Permission: settings.manage
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
url | string | Yes | HTTPS URL to receive webhook deliveries (max 2,048 characters) |
events | array | Yes | Array of event names to subscribe to (at least one) |
config | object | No | Advanced configuration (HTTP method, headers, payload format, conditions, timeout, max retries) |
Example Request
curl -X POST "https://your-domain.com/api/v1/webhooks" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"url":"https://hooks.example.com/webhook","events":["contact.created","document.sent"]}'const response = await fetch("https://your-domain.com/api/v1/webhooks", {
method: "POST",
headers: {
"Authorization": "Bearer YOUR_API_TOKEN",
"Accept": "application/json",
"Content-Type": "application/json"
},
body: JSON.stringify({
url: "https://hooks.example.com/webhook",
events: ["contact.created", "document.sent"]
})
});
const data = await response.json();$ch = curl_init("https://your-domain.com/api/v1/webhooks");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode([
"url" => "https://hooks.example.com/webhook",
"events" => ["contact.created", "document.sent"],
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer YOUR_API_TOKEN",
"Accept: application/json",
"Content-Type: application/json",
],
]);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);import requests
response = requests.post(
"https://your-domain.com/api/v1/webhooks",
headers={
"Authorization": "Bearer YOUR_API_TOKEN",
"Accept": "application/json"
},
json={
"url": "https://hooks.example.com/webhook",
"events": ["contact.created", "document.sent"]
}
)
data = response.json()Example Response (201 Created)
{
"data": {
"id": 2,
"url": "https://hooks.example.com/webhook",
"events": ["contact.created", "document.sent"],
"config": null,
"status": "active",
"failure_count": 0,
"last_delivery_at": null,
"disabled_at": null,
"created_at": "2025-06-02T10:00:00.000000Z",
"updated_at": "2025-06-02T10:00:00.000000Z"
},
"secret": "whsec_abc123...64chars..."
}Important: The secret is returned only once at creation. Store it securely for HMAC signature verification.
Get Webhook
GET /api/v1/webhooks/{id} — Permission: settings.manage
Returns the webhook endpoint with up to 10 recent deliveries.
Update Webhook
PUT /api/v1/webhooks/{id} — Permission: settings.manage
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
url | string | No | New HTTPS URL |
events | array | No | Updated event subscriptions |
status | string | No | active or paused |
config | object | No | Updated advanced configuration |
Example Request
curl -X PUT "https://your-domain.com/api/v1/webhooks/1" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"status": "paused"}'const response = await fetch("https://your-domain.com/api/v1/webhooks/1", {
method: "PUT",
headers: {
"Authorization": "Bearer YOUR_API_TOKEN",
"Accept": "application/json",
"Content-Type": "application/json"
},
body: JSON.stringify({ status: "paused" })
});
const data = await response.json();$ch = curl_init("https://your-domain.com/api/v1/webhooks/1");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode(["status" => "paused"]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer YOUR_API_TOKEN",
"Accept: application/json",
"Content-Type: application/json",
],
]);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);import requests
response = requests.put(
"https://your-domain.com/api/v1/webhooks/1",
headers={
"Authorization": "Bearer YOUR_API_TOKEN",
"Accept": "application/json"
},
json={"status": "paused"}
)
data = response.json()Delete Webhook
DELETE /api/v1/webhooks/{id} — Permission: settings.manage
Example Request
curl -X DELETE "https://your-domain.com/api/v1/webhooks/1" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json"const response = await fetch("https://your-domain.com/api/v1/webhooks/1", {
method: "DELETE",
headers: {
"Authorization": "Bearer YOUR_API_TOKEN",
"Accept": "application/json"
}
});
// 204 No Content$ch = curl_init("https://your-domain.com/api/v1/webhooks/1");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "DELETE",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer YOUR_API_TOKEN",
"Accept: application/json",
],
]);
$response = curl_exec($ch);
curl_close($ch);
// 204 No Contentimport requests
response = requests.delete(
"https://your-domain.com/api/v1/webhooks/1",
headers={
"Authorization": "Bearer YOUR_API_TOKEN",
"Accept": "application/json"
}
)
# 204 No ContentReturns 204 No Content on success.
Was this article helpful?