curl --request POST \
--url https://api.affinity.co/v2/webhooks \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"url": "https://example.com/affinity-events",
"subscriptions": [
"list.created"
]
}
'import requests
url = "https://api.affinity.co/v2/webhooks"
payload = {
"url": "https://example.com/affinity-events",
"subscriptions": ["list.created"]
}
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({url: 'https://example.com/affinity-events', subscriptions: ['list.created']})
};
fetch('https://api.affinity.co/v2/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.affinity.co/v2/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([
'url' => 'https://example.com/affinity-events',
'subscriptions' => [
'list.created'
]
]),
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.affinity.co/v2/webhooks"
payload := strings.NewReader("{\n \"url\": \"https://example.com/affinity-events\",\n \"subscriptions\": [\n \"list.created\"\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.affinity.co/v2/webhooks")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"url\": \"https://example.com/affinity-events\",\n \"subscriptions\": [\n \"list.created\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.affinity.co/v2/webhooks")
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 \"url\": \"https://example.com/affinity-events\",\n \"subscriptions\": [\n \"list.created\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"id": 1,
"url": "https://example.com/affinity-events",
"subscriptions": [
"list.created"
],
"status": "active",
"creator": {
"id": 1
},
"createdAt": "2026-01-01T00:00:00Z",
"updatedAt": "2026-01-01T00:00:00Z"
}{
"errors": [
{
"code": "bad-request",
"message": "<string>"
}
]
}{
"errors": [
{
"code": "not-found",
"message": "<string>"
}
]
}{
"errors": [
{
"code": "authentication",
"message": "<string>"
}
]
}Create a Webhook
| ⚠️ This endpoint is currently in BETA |
|---|
Creates a new Webhook. The creator of the new webhook is the user associated with the API key.
The URL is validated with a test delivery before the webhook is created. The request is rejected with a validation error on the url property when the URL is invalid or unreachable, contains embedded credentials, or already belongs to another webhook in the organization.
The request is rejected with a bad-request error, which has no associated property, when the organization has reached its webhook limit.
curl --request POST \
--url https://api.affinity.co/v2/webhooks \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"url": "https://example.com/affinity-events",
"subscriptions": [
"list.created"
]
}
'import requests
url = "https://api.affinity.co/v2/webhooks"
payload = {
"url": "https://example.com/affinity-events",
"subscriptions": ["list.created"]
}
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({url: 'https://example.com/affinity-events', subscriptions: ['list.created']})
};
fetch('https://api.affinity.co/v2/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.affinity.co/v2/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([
'url' => 'https://example.com/affinity-events',
'subscriptions' => [
'list.created'
]
]),
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.affinity.co/v2/webhooks"
payload := strings.NewReader("{\n \"url\": \"https://example.com/affinity-events\",\n \"subscriptions\": [\n \"list.created\"\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.affinity.co/v2/webhooks")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"url\": \"https://example.com/affinity-events\",\n \"subscriptions\": [\n \"list.created\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.affinity.co/v2/webhooks")
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 \"url\": \"https://example.com/affinity-events\",\n \"subscriptions\": [\n \"list.created\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"id": 1,
"url": "https://example.com/affinity-events",
"subscriptions": [
"list.created"
],
"status": "active",
"creator": {
"id": 1
},
"createdAt": "2026-01-01T00:00:00Z",
"updatedAt": "2026-01-01T00:00:00Z"
}{
"errors": [
{
"code": "bad-request",
"message": "<string>"
}
]
}{
"errors": [
{
"code": "not-found",
"message": "<string>"
}
]
}{
"errors": [
{
"code": "authentication",
"message": "<string>"
}
]
}Authorizations
A static Affinity API key, presented as a bearer token.
Body
Request body for creating a webhook. The URL is validated with a test delivery before the webhook is created.
The URL event payloads are delivered to. Must be unique within the organization.
"https://example.com/affinity-events"
The event types the webhook receives. An empty array subscribes the webhook to all event types.
100An event type a webhook can subscribe to. Values match the type field of delivered webhook payloads and are shared with the v1 webhook API.
list.created, list.updated, list.deleted, list_entry.created, list_entry.deleted, note.created, note.updated, note.deleted, field.created, field.updated, field.deleted, field_value.created, field_value.updated, field_value.deleted, person.created, person.updated, person.deleted, organization.created, organization.updated, organization.deleted, organization.merged, opportunity.created, opportunity.updated, opportunity.deleted, file.created, file.deleted, smart_interaction_value.updated, reminder.created, reminder.updated, reminder.deleted Response
Created
A webhook subscription that delivers event notifications to an external URL.
The webhook's unique identifier
1 <= x <= 90071992547409911
The URL event payloads are delivered to.
"https://example.com/affinity-events"
The event types this webhook receives. An empty array means the webhook receives all event types.
100An event type a webhook can subscribe to. Values match the type field of delivered webhook payloads and are shared with the v1 webhook API.
list.created, list.updated, list.deleted, list_entry.created, list_entry.deleted, note.created, note.updated, note.deleted, field.created, field.updated, field.deleted, field_value.created, field_value.updated, field_value.deleted, person.created, person.updated, person.deleted, organization.created, organization.updated, organization.deleted, organization.merged, opportunity.created, opportunity.updated, opportunity.deleted, file.created, file.deleted, smart_interaction_value.updated, reminder.created, reminder.updated, reminder.deleted Whether the webhook currently delivers events. A disabled webhook keeps its configuration but does not deliver events.
active, disabled "active"
The person who created the webhook. null when the creator is not recorded.
Show child attributes
Show child attributes
When the webhook was created.
"2026-01-01T00:00:00Z"
When the webhook was last updated. null if the webhook has never been updated.
"2026-01-01T00:00:00Z"
Was this page helpful?