Your AI Connector Docs

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 name nä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. Vanlig http://, localhost, adresser i privata nätverk och interna plattformsadresser avvisas med 400.

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 /webhooks rapporterar 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}/health som is_disabled och rensas med POST /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 nyttolasts user-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_enabledPOST /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