Webhook-slutpunkter

Hantera flera webhook-URL:er med hemligheter och händelsefilter per slutpunkt.

Det endpointbaserade webhook-systemet låter dig registrera flera destinationer per organisation, var och en med sin egen hemlighet, sin egen status och sin egen prenumeration på en delmängd av händelsetyper. Detta är den rekommenderade modellen för alla nya integrationer.

Jämför med den äldre webhooken med en enda URL, som behålls för bakåtkompatibilitet men endast stöder en URL per organisation.

Slutpunkter#

Slutpunktsobjekt#

{
  "id": "c4d5e6f7-...",
  "label": "Production — Call events",
  "url": "https://example.com/thunderphone/hook",
  "events": ["telephony.incoming", "telephony.complete"],
  "status": "active",
  "agent_id": 42,
  "agent_name": "Support Agent",
  "secret_hint": "a1b2…9f0e",
  "paused_at": null,
  "pause_last_error": "",
  "pause_undelivered_count": null,
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z"
}

Giltiga händelsetyper#

events valideras mot exakt denna uppsättning — värden utanför listan returnerar 400. Se Händelsekatalog för varje typs payload-format.

• telephony.incoming, telephony.complete, telephony.tool, telephony.turn
• web.incoming, web.complete, web.tool, web.turn
• sms.sent, sms.failed
• sms.received (reserverad; ännu inte skickad)
• call.graded, call.data_extracted, call.transfer_completed
• campaign.completed
• issue.reported, issue.escalated
• test-call.completed
• alert.triggered

issue.escalated har inget agentkontext och levereras endast till organisationsomfattande slutpunkter.

voice.ready och voice.failed kan inte väljas uttryckligen. Skapa en organisationsomfattande slutpunkt med events: [] för att ta emot dem. En tom händelselista tar emot alla händelser som stöds utom telephony.turn och web.turn, som måste väljas uttryckligen.

Slutpunktsstatusar#

• active — leveranser fungerar normalt.
• disabled — pausad manuellt via PATCH. Inga förfrågningar skickas. Vi ändrar aldrig statusen för en disabled-endpoint; att ändra tillbaka den till active är alltid ditt beslut.
• failing — ställs in automatiskt när en leverans till endpointen förbrukar hela sitt återförsöksschema (8 försök under 24 timmar) utan att någonsin få en 2xx. En felande endpoint tar inte emot någon ytterligare trafik. Vi skickar e-post till organisationens ägare och administratörer när detta händer, och instrumentpanelen visar den pausade endpointen med en knapp för att återaktivera. När endpointen har åtgärdats, ändra dess status med PATCH tillbaka till active; leveranser vars återförsöksschema ännu inte har löpt ut återupptas där de slutade.

Lista slutpunkter#

curl https://api.thunderphone.com/v1/developer/webhook-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Returnerar en array med slutpunktsobjekt. Ange ?agent_id=42 för att endast returnera slutpunkter som är begränsade till den agenten.

Agentspecifika slutpunkter#

Organisationsomfattande slutpunkter tar emot varje matchande händelse. En slutpunkt med agent_id tar endast emot matchande händelser för samtal som hanteras av den agenten; händelser utan agentkontext, exempelvis alert.triggered, når den aldrig. Du kan också skapa och hantera dessa slutpunkter från avsnittet Webhooks i agentbyggaren.

Skapa en slutpunkt#

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label":  "Production — Call events",
    "url":    "https://example.com/thunderphone/hook",
    "events": ["telephony.incoming", "telephony.complete"]
  }'

result = requests.post(
    "https://api.thunderphone.com/v1/developer/webhook-endpoints",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
    json={
        "label":  "Production — Call events",
        "url":    "https://example.com/thunderphone/hook",
        "events": ["telephony.incoming", "telephony.complete"],
    },
).json()
secret = result["secret"]
endpoint_id = result["id"]

Begärandefält#

Returnerar 201 Created med slutpunktsobjektet samt ett extra secret-fält på toppnivå som innehåller den råa signeringsnyckeln — en hexadecimala sträng med 48 tecken:

{
  "id": "c4d5e6f7-…",
  "label": "Production — Call events",
  "url": "https://example.com/thunderphone/hook",
  "events": ["telephony.incoming", "telephony.complete"],
  "status": "active",
  "secret_hint": "a1b2…9f0e",
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z",
  "secret": "a1b2c37e08d94f5b16a2c8d90e7f3a4b5c6d7e8f90a19f0e"
}

Uppdatera en slutpunkt#

curl -X PATCH https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label":  "Production — Call + Grade events",
    "events": ["telephony.incoming", "telephony.complete", "call.graded"]
  }'

Returnerar 200 OK med det uppdaterade slutpunktsobjektet.

Rotera signeringshemligheten#

Ersätt en slutpunkts signeringshemlighet, till exempel om den har gått förlorad eller kan ha läckt. För en agentspecifik slutpunkt kan du även använda instrumentpanelen: öppna agentens avsnitt Webhooks och välj Återskapa hemlighet på slutpunkten. Organisationsomfattande slutpunkter roteras via API:t.

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../rotate-secret \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Returnerar 200 OK:

{
  "endpoint": { "id": "c4d5e6f7-...", "secret_hint": "7f3a…c21d", "...": "..." },
  "secret": "7f3a90b2c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5c21d",
  "rotated_endpoint_ids": ["c4d5e6f7-..."]
}

Skicka en testleverans#

Skicka en syntetisk webhook.test-händelse till en endpoint via den vanliga leveransprocessen, inklusive kanonisk JSON-serialisering, båda signaturhuvudena, leveransloggning och hantering av återförsök. Testet riktas mot den valda endpointen oavsett dess events-filter.

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Slutpunkten tar emot ett kuvert som detta:

{
  "data": {
    "message": "ThunderPhone webhook test",
    "sent_at": "2026-07-17T20:12:34.567890+00:00"
  },
  "event_id": "2ad6507c-7d19-4498-9b2d-7e8f944ab5a1",
  "type": "webhook.test"
}

API:et returnerar 200 OK efter det första försöket, även om destinationen returnerar ett fel. Kontrollera success, status, response_code och error för leveransresultatet:

{
  "success": true,
  "event_id": "2ad6507c-7d19-4498-9b2d-7e8f944ab5a1",
  "event_type": "webhook.test",
  "status": "delivered",
  "response_code": 204,
  "error": ""
}

webhook.test är syntetisk och kan inte läggas till i en slutpunkts events- prenumeration. Om det första försöket misslyckas försöker ThunderPhone igen en gång ungefär en minut senare och stoppar sedan; leveransen visas då med status: "failed" under Felsök leveranser. En testleverans markerar aldrig slutpunkten som failing.

Om du vill konfigurera en utlösare mot en verklig händelseform kan du skicka ett valfritt event_type. Leveransen är fortfarande syntetisk och innehåller "sample": true; samtalsrelaterade exempel använder call_id: 0 och agent_id: 0.

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_type":"call.graded"}'

event_type accepterar alla värden från Giltiga händelsetyper. Om du utelämnar det behålls det generella webhook.test-beteendet.

Ta bort en slutpunkt#

curl -X DELETE https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Returnerar 204 No Content. Leverans till URL:en stoppas omedelbart; pågående återförsök avbryts.

Felsök leveranser#

Innan du drar slutsatsen att en webhook inte skickades bör du kontrollera GET /v1/developer/webhook-deliveries. Den visar senaste försök från båda webhook-systemen, inklusive samtals-id, URL-ursprung, HTTP-status, antal försök, vitlistad felkategori och tid för nästa återförsök. Den returnerar aldrig händelsens nyttolast, transkription, lagrad feltext, svarstext eller URL-sökväg.

Du kan även se samma senaste historik i Agenter → välj en agent → Webhooks → Senaste leveranser. Rader visar slutpunktens etikett och det URL-ursprung som användes vid det senaste försöket. Detta är driftstatus snarare än en oföränderlig granskningslogg: om du tar bort en slutpunkt tas även dess leveransrader bort.

För en n8n-404 ska du först bekräfta att arbetsflödet är aktivt, accepterar POST och använder produktionswebhookens URL i stället för test-URL:en. En 401 eller 403 pekar på autentisering eller signaturvalidering; tidsgränser pekar på fördröjning eller tillgänglighet hos destinationen; TLS-fel pekar på certifikatkedjan, värdnamnet eller utgångsdatumet.

Relaterat#