Skip to main content
POST
/
v2
/
webhooks
curl --location --request POST 'https://api.audienceful.com/v2/webhooks' \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: <your-api-key>' \
--data-raw '{
    "url": "https://example.com/webhooks/audienceful",
    "events": ["person.created", "person.updated"]
}'

import requests

url = "https://api.audienceful.com/v2/webhooks"
headers = {
    "Content-Type": "application/json",
    "X-Api-Key": "<your-api-key>",
}
payload = {
    "url": "https://example.com/webhooks/audienceful",
    "events": ["person.created", "person.updated"],
}

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

const response = await fetch("https://api.audienceful.com/v2/webhooks", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Api-Key": "<your-api-key>",
  },
  body: JSON.stringify({
    "url": "https://example.com/webhooks/audienceful",
    "events": [
      "person.created",
      "person.updated"
    ]
  }),
});
const data = await response.json();
console.log(data);

{
  "id": "wYt3nKq8Zs4pLm9vRb2xJc",
  "url": "https://example.com/webhooks/audienceful",
  "events": ["person.created", "person.updated"],
  "is_active": true,
  "disabled_reason": null,
  "disabled_at": null,
  "consecutive_failures": 0,
  "created_at": "2026-07-04T12:00:00Z",
  "updated_at": "2026-07-04T12:00:00Z",
  "secret": "whsec_9f2c1a7e5b8d4f31a0c6e2d9b7a4f108ef01a2b3c4d5e6f708192a3b4c5d6ef0"
}
Requires the webhooks:write scope.
The creation response is the only time the signing secret is returned. Store it securely — you’ll need it to verify signatures, and it can’t be retrieved again.

​
Body

​
url
string
required
The endpoint URL to deliver events to. Must be HTTPS.
​
events
array[string]
required
The events to subscribe to. Must be a non-empty list of valid event names — see List Available Events.

​
Response

Returns 201 Created with the endpoint, including the one-time secret.
​
id
string
The webhook endpoint's unique id.
​
url
string
The HTTPS URL deliveries are POSTed to.
​
events
array[string]
The events this endpoint is subscribed to.
​
is_active
boolean
Whether the endpoint is currently active. A disabled endpoint receives no deliveries.
​
disabled_reason
string or null
Why the endpoint was disabled, if it is. One of manual, 410_gone, or too_many_failures. null when active.
​
disabled_at
string or null
The datetime (UTC) the endpoint was disabled, if it is.
​
consecutive_failures
number
The number of consecutive failed deliveries. Resets to 0 on a successful delivery or when the endpoint is re-enabled.
​
created_at
string
The datetime (UTC) the endpoint was created.
​
updated_at
string
The datetime (UTC) the endpoint was last updated.
​
secret
string
The HMAC signing secret, returned only in this creation response. Store it securely.
curl --location --request POST 'https://api.audienceful.com/v2/webhooks' \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: <your-api-key>' \
--data-raw '{
    "url": "https://example.com/webhooks/audienceful",
    "events": ["person.created", "person.updated"]
}'

import requests

url = "https://api.audienceful.com/v2/webhooks"
headers = {
    "Content-Type": "application/json",
    "X-Api-Key": "<your-api-key>",
}
payload = {
    "url": "https://example.com/webhooks/audienceful",
    "events": ["person.created", "person.updated"],
}

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

const response = await fetch("https://api.audienceful.com/v2/webhooks", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Api-Key": "<your-api-key>",
  },
  body: JSON.stringify({
    "url": "https://example.com/webhooks/audienceful",
    "events": [
      "person.created",
      "person.updated"
    ]
  }),
});
const data = await response.json();
console.log(data);

{
  "id": "wYt3nKq8Zs4pLm9vRb2xJc",
  "url": "https://example.com/webhooks/audienceful",
  "events": ["person.created", "person.updated"],
  "is_active": true,
  "disabled_reason": null,
  "disabled_at": null,
  "consecutive_failures": 0,
  "created_at": "2026-07-04T12:00:00Z",
  "updated_at": "2026-07-04T12:00:00Z",
  "secret": "whsec_9f2c1a7e5b8d4f31a0c6e2d9b7a4f108ef01a2b3c4d5e6f708192a3b4c5d6ef0"
}