Webhooks-API
Webhooks låter plattformen meddela dina andra system i samma ögonblick som något händer — en ny kontakt, ett svar, en bokad tid och mer. Detta API hanterar själva prenumerationerna: vilka URL:er som tar emot vilka händelser. För information om hur du tar emot och verifierar nyttolasterna som din slutpunkt får, se Webhooks.
Alla sökvägar nedan är relativa till API:ets bas-URL:
https://api.youraiconnector.com/v1
Varje begäran måste autentiseras. Se Autentisering för de fyra accepterade metoderna. Exemplen här använder X-API-Key-huvudet (och en form med frågeparameter för cURL).
Obs: Webhooks måste vara aktiverade för ditt konto. Om de inte är det returnerar dessa slutpunkter ett 403.
Hur prenumerationer adresseras
Varje prenumeration har ett id och ett valfritt name. Båda kan användas som {webhookId} i sökvägen för uppdatering, borttagning, test, hälsa och återaktivering.
Föredra namnet. Prenumerations-ID:n är positionella, så de kan ändras efter att en annan prenumeration har tagits bort. Om du anger ett stabilt
namenär du skapar en prenumeration, adressera den med namn för att undvika överraskningar.
Lista prenumerationer
GET /webhooks
cURL
curl "https://api.youraiconnector.com/v1/webhooks?apiKey=YOUR_API_KEY"
JavaScript
const res = await fetch("https://api.youraiconnector.com/v1/webhooks", {
headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
Python
import requests
res = requests.get(
"https://api.youraiconnector.com/v1/webhooks",
headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
Svar
{
"success": true,
"webhooks": [
{
"id": "0",
"name": "Order updates hook",
"url": "https://hooks.example.com/incoming",
"subscribed_to": ["Contact Created", "Replies"],
"subscribed_to_tags": [],
"created_at": "2026-06-09T12:00:00.000Z",
"signing_enabled": true,
"signing_secret_created_at": "2026-07-15T09:30:00.000Z",
"retries_enabled": true,
"enabled": true,
"apply_to_sub_accounts": false
}
]
}
signing_enabled och retries_enabled är tillval per prenumeration, båda är avstängda om du inte aktiverar dem. Se Signerade nyttolaster och Försök igen.
apply_to_sub_accounts är inställningen för arv av byråkonton — se En prenumeration för alla klientkonton. Avstängd som standard och inaktiv på konton som inte har några klientkonton.
enabled är prenumerationens på/av-knapp — se Stänga av en prenumeration. Avstängda prenumerationer listas fortfarande här.
Själva signeringshemligheten inkluderas aldrig här — läs den från GET /webhooks/{id}/signing-secret.
Lista prenumererbara händelsetyper
Returnerar de exakta strängar du kan använda i subscribed_to. Använd detta för att upptäcka giltiga händelsenamn istället för att hårdkoda dem.
GET /webhooks/events
cURL
curl "https://api.youraiconnector.com/v1/webhooks/events" \
-H "X-API-Key: YOUR_API_KEY"
JavaScript
const res = await fetch("https://api.youraiconnector.com/v1/webhooks/events", {
headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
Python
import requests
res = requests.get(
"https://api.youraiconnector.com/v1/webhooks/events",
headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
Svar
Svaret är {"success": true, "events": [...]}, där events för närvarande innehåller 22 exakta strängar: Contact Created, Human Alerted, Appointment Booked, Replies, Reads, Deliveries, Credits Spent, Credits Recharged, Low Credit Balance, Contact Paused, Contact Do Not Disturb, Contact Unarchived, New Message, Contact Resumed, Chat Concluded, Task Created, Task Updated, Task Completed, Daily Summary Created, Channel Connected, Broadcast Started och Broadcast Completed (Channel Connected accepteras i subscribed_to men ingenting skickar det idag, så bygg inte mot det).
För vad varje händelse betyder och den event-kod som skickas i nyttolasten, se De 22 webhook-händelserna. Denna slutpunkt är den auktoritativa listan vid varje givet tillfälle — läs den live istället för att hårdkoda namnen.
Skapa en prenumeration
POST /webhooks
| Fält | Krävs | Beskrivning |
|---|---|---|
url |
Ja | HTTPS-URL som tar emot händelsenyttolaster via POST. Måste vara publikt nåbar. |
subscribed_to |
Ja | En icke-tom array med händelsenamn (se /webhooks/events). |
name |
Nej | Ett visningsnamn. Kan även användas som {webhookId} senare. Standard är ett tidsstämplat namn. |
subscribed_to_tags |
Nej | Tagg-ID:n som begränsar vilka taggar som skapar ett meddelande om konversationssammanfattning. Det begränsar inte prenumerationens händelser till dessa taggar — för att få en förfrågan när en specifik tagg appliceras, ställ in en webhook-URL på den taggen under fliken Taggar för agenten (eller kampanjen). |
retries_enabled |
Nej | Booleskt värde, standard är false. Välj att aktivera återförsök vid misslyckade leveranser. |
generate_signing_secret |
Nej | Booleskt värde, standard är false. Skapa en HMAC-signeringshemlighet med prenumerationen. Hemligheten returneras en gång, som en signing_secret på toppnivå i svaret. |
enabled |
Nej | Booleskt värde, standard är true. Skicka false för att skapa prenumerationen i avstängt läge. Se Stänga av en prenumeration. |
apply_to_sub_accounts |
Nej | Booleskt värde, standard är false. På ett byråkonto gör true att denna prenumeration även tar emot händelser från alla klientkonton — se En prenumeration för alla klientkonton. |
URL-regler: URL:en måste använda
https://och vara offentligt tillgänglig. Vanlighttp://,localhost, adresser i privata nätverk och interna plattformsadresser avvisas med400.
cURL
curl -X POST "https://api.youraiconnector.com/v1/webhooks?apiKey=YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://hooks.example.com/incoming",
"subscribed_to": ["Contact Created", "Replies"],
"name": "Order updates hook"
}'
JavaScript
const res = await fetch("https://api.youraiconnector.com/v1/webhooks", {
method: "POST",
headers: {
"X-API-Key": "YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
url: "https://hooks.example.com/incoming",
subscribed_to: ["Contact Created", "Replies"],
name: "Order updates hook",
}),
});
const data = await res.json();
Python
import requests
res = requests.post(
"https://api.youraiconnector.com/v1/webhooks",
headers={"X-API-Key": "YOUR_API_KEY"},
json={
"url": "https://hooks.example.com/incoming",
"subscribed_to": ["Contact Created", "Replies"],
"name": "Order updates hook",
},
)
data = res.json()
Svar
{
"success": true,
"webhook_id": "1",
"webhook": {
"id": "1",
"name": "Order updates hook",
"url": "https://hooks.example.com/incoming",
"subscribed_to": ["Contact Created", "Replies"],
"subscribed_to_tags": [],
"created_at": "2026-06-09T12:00:00.000Z"
}
}
Uppdatera en prenumeration
Ange minst ett av url, subscribed_to, name, subscribed_to_tags, retries_enabled, enabled eller apply_to_sub_accounts. Utelämnade fält behåller sina nuvarande värden. subscribed_to och subscribed_to_tags är ersättningar, inte sammanslagningar.
PUT /webhooks/{webhookId}
Att uppdatera en prenumeration påverkar aldrig dess signeringshemlighet — hantera den via rutter för signeringshemligheter.
När URL:en ändras återaktiveras leveransen för den nya URL:en automatiskt, vilket ger en tidigare misslyckad slutpunkt en nystart.
cURL
curl -X PUT "https://api.youraiconnector.com/v1/webhooks/Order%20updates%20hook" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://hooks.example.com/v2/incoming",
"subscribed_to": ["Replies", "Chat Concluded"]
}'
JavaScript
const res = await fetch(
`https://api.youraiconnector.com/v1/webhooks/${encodeURIComponent("Order updates hook")}`,
{
method: "PUT",
headers: {
"X-API-Key": "YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
url: "https://hooks.example.com/v2/incoming",
subscribed_to: ["Replies", "Chat Concluded"],
}),
}
);
const data = await res.json();
Python
import requests
res = requests.put(
"https://api.youraiconnector.com/v1/webhooks/Order updates hook",
headers={"X-API-Key": "YOUR_API_KEY"},
json={
"url": "https://hooks.example.com/v2/incoming",
"subscribed_to": ["Replies", "Chat Concluded"],
},
)
data = res.json()
Svar
{
"success": true,
"webhook_id": "0",
"webhook": {
"id": "0",
"name": "Order updates hook",
"url": "https://hooks.example.com/v2/incoming",
"subscribed_to": ["Replies", "Chat Concluded"],
"subscribed_to_tags": [],
"created_at": "2026-06-09T12:00:00.000Z"
}
}
Ett okänt ID eller namn returnerar 404 med { "success": false, "error": "Webhook not found" }.
Ta bort en prenumeration
Tar bort prenumerationen så att dess URL slutar ta emot nyttolaster. Dess räknare för leveransstatus återställs, så att om du lägger till samma URL igen senare börjar den med ett rent register.
DELETE /webhooks/{webhookId}
cURL
curl -X DELETE "https://api.youraiconnector.com/v1/webhooks/0" \
-H "X-API-Key: YOUR_API_KEY"
JavaScript
const res = await fetch("https://api.youraiconnector.com/v1/webhooks/0", {
method: "DELETE",
headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
Python
import requests
res = requests.delete(
"https://api.youraiconnector.com/v1/webhooks/0",
headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
Svar
{
"success": true
}
Skicka en testnyttolast
Skickar en exempelnyttolast till prenumerationens URL så att du kan verifiera din mottagare från slutpunkt till slutpunkt. Skicka valfritt med en event för att styra vilken händelsetyp exemplet simulerar. Testleveranser påverkar aldrig prenumerationens hälsoräknare.
POST /webhooks/{webhookId}/test
Svaret returnerar alltid 200 och rapporterar resultatet med en delivered-flagga — ett misslyckat test returnerar inte en felstatus. När delivered är false inkluderar svaret feldetaljerna.
| Fält | Krävs | Beskrivning |
|---|---|---|
event |
Nej | Händelsetyp att simulera (måste vara en av /webhooks/events). Standard är en leveranshändelse. |
cURL
curl -X POST "https://api.youraiconnector.com/v1/webhooks/0/test?apiKey=YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "event": "Contact Created" }'
JavaScript
const res = await fetch("https://api.youraiconnector.com/v1/webhooks/0/test", {
method: "POST",
headers: {
"X-API-Key": "YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({ event: "Contact Created" }),
});
const data = await res.json();
Python
import requests
res = requests.post(
"https://api.youraiconnector.com/v1/webhooks/0/test",
headers={"X-API-Key": "YOUR_API_KEY"},
json={"event": "Contact Created"},
)
data = res.json()
Svar (levererat)
{
"success": true,
"webhook_id": "0",
"delivered": true
}
Svar (misslyckades)
{
"success": true,
"webhook_id": "0",
"delivered": false,
"failure_type": "permanent",
"status_code": 404,
"error_message": "Request failed with status code 404"
}
failure_type är en av permanent, temporary, timeout, network eller unknown.
Kontrollera leveransstatus
Returnerar leveransstatusposten för prenumerationens URL: hur många leveranser som har lyckats och misslyckats, om leveransen för närvarande är pausad efter upprepade fel, samt detaljer om det senaste felet. Returnerar "health": null när inga leveranser har försökts ännu.
GET /webhooks/{webhookId}/health
cURL
curl "https://api.youraiconnector.com/v1/webhooks/0/health" \
-H "X-API-Key: YOUR_API_KEY"
JavaScript
const res = await fetch("https://api.youraiconnector.com/v1/webhooks/0/health", {
headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
Python
import requests
res = requests.get(
"https://api.youraiconnector.com/v1/webhooks/0/health",
headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
Svar
{
"success": true,
"webhook_id": "0",
"url": "https://hooks.example.com/incoming",
"health": {
"consecutive_failures": 0,
"total_failures": 2,
"total_successes": 120,
"is_disabled": false,
"disabled_at": null,
"disabled_reason": null,
"last_failure": null,
"last_success_at": "2026-06-09T12:00:00.000Z",
"created_at": "2026-05-01T08:00:00.000Z",
"updated_at": "2026-06-09T12:00:00.000Z"
}
}
När is_disabled är true har leverans till URL:en pausats automatiskt efter upprepade fel. Åtgärda din mottagare och återaktivera den sedan (nedan).
Återaktivera leverans
Återupptar leverans för en webhook vars URL pausades automatiskt efter upprepade fel. Detta återställer pausflaggan och felräknarna men gör inte ett leveransförsök — använd test-slutpunkten efteråt för att bekräfta att din mottagare är frisk igen.
POST /webhooks/{webhookId}/reenable
cURL
curl -X POST "https://api.youraiconnector.com/v1/webhooks/0/reenable?apiKey=YOUR_API_KEY"
JavaScript
const res = await fetch("https://api.youraiconnector.com/v1/webhooks/0/reenable", {
method: "POST",
headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
Python
import requests
res = requests.post(
"https://api.youraiconnector.com/v1/webhooks/0/reenable",
headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
Svar
{
"success": true,
"webhook_id": "0"
}
Stänga av en prenumeration
enabled är prenumerationens egen på/av-knapp. Att stänga av den stoppar leveranser samtidigt som URL, händelselista och signeringshemlighet förblir intakta.
# Off
curl -X PUT "https://api.youraiconnector.com/v1/webhooks/0?apiKey=YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"enabled": false}'
# Back on
curl -X PUT "https://api.youraiconnector.com/v1/webhooks/0?apiKey=YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"enabled": true}'
- Frånvaro betyder på. En prenumeration som skapades innan detta fält existerade har inget
enabled-värde lagrat och levererar normalt.GET /webhooksrapporterar alltid ett konkret booleskt värde. - Avstängda prenumerationer listas fortfarande av
GET /webhooks— det är så du hittar dem för att slå på dem igen. - Ett försök igen som köats före avstängningen återupptas inte: försöket läser av prenumerationen på nytt vid sändningstillfället och avbryts om den är avstängd.
- Ingenting som undertryckts under tiden den varit avstängd spelas upp igen när du slår på den.
Skiljer sig från den automatiska inaktiveringen efter upprepade fel, vilket rapporteras av
GET /webhooks/{id}/healthsomis_disabledoch rensas medPOST /webhooks/{id}/reenable.enabledär kontots knapp;is_disabledär vår. Ingen av dem åsidosätter den andra — en prenumeration måste vara både påslagen och inte automatiskt inaktiverad för att leverera.
En prenumeration för alla klientkonton (byråer)
På ett byråkonto, ställ in apply_to_sub_accounts: true på en prenumeration (vid skapandet eller via PUT) så tar den även emot händelser som sker på alla byråns klientkonton — en slutpunkt täcker hela byrån, istället för att återskapa prenumerationen på varje klientkonto.
curl -X PUT "https://api.youraiconnector.com/v1/webhooks/0?apiKey=YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"apply_to_sub_accounts": true}'
Så här fungerar det:
user-blocket skiljer kontona åt. Varje nyttolastsuser-block identifierar kontot där händelsen faktiskt inträffade, så att din mottagare kan dirigera per klient.- Byråprenumerationens egna inställningar gäller överallt. Dess händelselista, signeringshemlighet och återförsöksinställning används även för de ärvda leveranserna.
- Ett klientkontos egen prenumeration till samma URL vinner. Om ett klientkonto har en egen prenumeration som pekar på samma URL, används den för det kontots händelser — samma händelse levereras aldrig två gånger till en slutpunkt.
- Klientkonton ser den inte. Ärvda prenumerationer visas inte i ett klientkontos egen webhook-lista, och klienten kan inte stänga av dem — endast byrån hanterar dem.
- Leveransstatus spåras per klientkonto. En slutpunkt som fortsätter att misslyckas inaktiveras automatiskt för det konto vars leveranser misslyckades, inte för hela byrån.
subscribed_to_tagsärvs inte. Tagglistan refererar till byråns egna taggar, som inte finns på klientkonton — begränsning av konversationssammanfattning gäller endast byråns egna händelser.- Inaktiv på andra ställen. På ett konto utan klientkonton lagras flaggan korrekt men gör ingenting.
Rubriker vid varje leverans
Dessa tre rubriker skickas vid varje leverans, oavsett om prenumerationen är signerad eller inte:
| Rubrik | Betydelse |
|---|---|
X-Webhook-Delivery |
Stabilt ID för den logiska händelsen. Identiskt vid upprepade försök — använd för deduplicering. |
X-Webhook-Attempt |
1-baserat försöksnummer. |
X-Webhook-Event |
Händelsenamnet. |
Signerade nyttolaster
Signering är valfritt, avstängt som standard och ställs in per prenumeration. När en prenumeration har en signeringshemlighet innehåller varje leverans ytterligare två rubriker utöver de tre som skickas vid varje leverans (X-Webhook-Delivery, X-Webhook-Attempt och X-Webhook-Event):
| Rubrik | Betydelse |
|---|---|
X-Webhook-Signature |
v1=<hex> — HMAC-SHA256 av strängen "<timestamp>.<raw request body>", nycklad med den webhook-specifika signeringshemlighet du skapar och roterar vid GET/POST/DELETE /v1/webhooks/{webhookId}/signing-secret. |
X-Webhook-Timestamp |
Sändningstid, Unix-sekunder. Bundet till signaturen, så det kan inte ändras oberoende. |
För att verifiera, beräkna HMAC-SHA256 på nytt över den råa kroppen med din hemlighet och jämför den med rubriken. Verifiera mot den råa förfrågningskroppen. Om-serialisering av parsad JSON ändrar byten och förstör jämförelsen. Avvisa leveranser vars tidsstämpel ligger utanför ett giltighetsfönster (300 sekunder är en rimlig standard) för att förhindra replay-attacker, och jämför med en tidsäker funktion.
Se Signerade nyttolaster för fullständiga exempel på verifiering i Node och Python.
Signering är inte samma sak som API-autentisering. REST-API:et i sig autentiserar med API-nycklar snarare än OAuth (OAuth 2.1 finns för MCP-servrar som du registrerar som bot-verktyg), och det finns inga officiella npm- eller PyPI-SDK-paket ännu — anropa slutpunkterna med valfri HTTP-klient.
Läs signeringshemligheten
GET /webhooks/{id}/signing-secret
curl "https://api.youraiconnector.com/v1/webhooks/0/signing-secret?apiKey=YOUR_API_KEY"
Svar
{
"success": true,
"webhook_id": "0",
"signing_enabled": true,
"signing_secret": "whsec_1a2b3c...",
"signing_secret_created_at": "2026-07-15T09:30:00.000Z"
}
När signering är avstängd är signing_enabled false och signing_secret är null.
Generera eller rotera signeringshemligheten
POST /webhooks/{id}/signing-secret
Skapar en hemlighet (aktiverar signering) eller ersätter den befintliga. Returnerar den nya hemligheten.
curl -X POST "https://api.youraiconnector.com/v1/webhooks/0/signing-secret?apiKey=YOUR_API_KEY"
Svar
{
"success": true,
"webhook_id": "0",
"signing_enabled": true,
"signing_secret": "whsec_9f8e7d...",
"signing_secret_created_at": "2026-07-15T10:00:00.000Z"
}
Rotationen träder i kraft omedelbart — nästa leverans signeras endast med den nya hemligheten. Acceptera båda hemligheterna under en kort period medan du rullar ut ändringen till en aktiv slutpunkt.
Du kan även skapa en hemlighet vid skapandetillfället genom att skicka "generate_signing_secret": true till POST /webhooks; svaret innehåller då ett signing_secret-fält på toppnivå.
Stäng av signering
DELETE /webhooks/{id}/signing-secret
curl -X DELETE "https://api.youraiconnector.com/v1/webhooks/0/signing-secret?apiKey=YOUR_API_KEY"
Svar
{
"success": true,
"webhook_id": "0",
"signing_enabled": false
}
Alla tre rutter för signeringshemligheter kräver behörigheten edit för integrationer, inklusive
GET— hemligheten är en autentiseringsuppgift som kan förfalska leveranser, så den exponeras inte för roller med skrivskyddad åtkomst.
Försök igen
Valfritt, avstängt som standard, och ställs in per prenumeration via det booleska värdet retries_enabled på POST /webhooks eller PUT /webhooks/{id}.
curl -X PUT "https://api.youraiconnector.com/v1/webhooks/0?apiKey=YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"retries_enabled": true}'
När det är aktiverat görs ett nytt försök vid en misslyckad leverans efter 1m, 5m, 30m och 2h från det första försöket (cirka 2h 40m täckning).
- Försöks igen: 5xx-svar, tidsgränser och anslutningsfel.
- Försöks ej igen: alla 4xx. Mottagaren avvisar själva begäran, så att skicka om den oförändrad leder bara till samma avvisande.
Återförsök gör dubbel leverans möjlig — en slutpunkt som bearbetade en händelse men fick timeout innan svar skickades kommer att se den igen. Deduplicera baserat på X-Webhook-Delivery, som är konstant vid alla försök. Det är därför återförsök är valfria.
Räknarna för delivery-health räknar en hel leverans, inte varje försök: ett fel registreras först när alla försök är uttömda, så att aktivera försök igen gör inte att den automatiska avstängningen utlöses tidigare.
Fel
Alla fel använder standardkuvertet:
{
"success": false,
"error": "Webhook not found"
}
Vanliga fall: en URL som inte är tillåten, en tom/ogiltig subscribed_to eller saknade fält returnerar 400; ett okänt id eller namn returnerar 404; och en 403 innebär att webhooks inte är aktiverade för ditt konto. Se Fel för hela listan.
Nästa steg
- Webhooks (ta emot nyttolaster) — konfigurera din mottagare och förstå nyttolastens form.
- Autentisering — de fyra sätten att autentisera en begäran.
- Fel och hastighetsbegränsningar — statuskoder och gränsen på 300 anrop/min.