Webhook-slutpunkter

Administrer flere webhook-URL

Det endpointbaserede webhook-system lader dig registrere flere destinationer pr. organisation, hver med sin egen hemmelighed, sin egen status og sit eget abonnement på et udvalg af hændelsestyper. Dette er den anbefalede model for alle nye integrationer.

Sammenlign med den ældre webhook med enkelt-URL, som bevares af hensyn til bagudkompatibilitet, men kun understøtter én URL pr. organisation.

Endepunkter#

Endpoint-objekt#

{
  "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"
}

Gyldige hændelsestyper#

events valideres mod præcis dette sæt — værdier uden for listen returnerer 400. Se Hændelseskatalog for hver types payloadstruktur.

• telephony.incoming, telephony.complete, telephony.tool, telephony.turn
• web.incoming, web.complete, web.tool, web.turn
• sms.sent, sms.failed
• sms.received (reserveret; udsendes endnu ikke)
• call.graded, call.data_extracted, call.transfer_completed
• campaign.completed
• issue.reported, issue.escalated
• test-call.completed
• alert.triggered

issue.escalated har ingen agentkontekst og leveres kun til organisationsdækkende endpoints.

voice.ready og voice.failed kan ikke vælges eksplicit. For at modtage dem skal du oprette et organisationsdækkende endpoint med events: []. En tom hændelsesliste modtager alle understøttede hændelser undtagen telephony.turn og web.turn, som skal vælges eksplicit.

Endpoint-statusser#

• active — leveringer forløber normalt.
• disabled — manuelt sat på pause via PATCH. Der sendes ingen anmodninger. Vi ændrer aldrig status for et disabled-endepunkt; det er altid dit valg at ændre det tilbage til active.
• failing — indstilles automatisk, når en levering til endepunktet bruger hele sin genforsøgsplan (8 forsøg over 24 timer) uden nogensinde at få en 2xx. Et fejlende endepunkt modtager ingen yderligere trafik. Vi sender en e-mail til din organisations ejere og administratorer, når dette sker, og dashboardet viser det pausede endepunkt med knappen Genaktivér. Når endepunktet er rettet, skal du PATCH-ændre dets status tilbage til active; leveringer, hvis genforsøgsplan endnu ikke er udløbet, fortsætter, hvor de slap.

Vis endpoints#

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

Returnerer et array af Endpoint-objekter. Angiv ?agent_id=42 for kun at returnere endpoints, der er afgrænset til den agent.

Agentafgrænsede endpoints#

Organisationsdækkende endpoints modtager alle matchende hændelser. Et endpoint med agent_id modtager kun matchende hændelser for opkald, der håndteres af den agent; hændelser uden agentkontekst, såsom alert.triggered, når det aldrig. Du kan også oprette og administrere disse endpoints fra afsnittet Webhooks i agentbyggeren.

Opret et endpoint#

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"]

Anmodningsfelter#

Returnerer 201 Created med det Endpoint-objekt samt et ekstra secret-felt på øverste niveau, der indeholder den rå signeringsnøgle — en hex-streng på 48 tegn:

{
  "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"
}

Opdater et endpoint#

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"]
  }'

Returnerer 200 OK med det opdaterede Endpoint-objekt.

Rotér signeringshemmeligheden#

Erstat et endpoints signeringshemmelighed, f.eks. når den er gået tabt eller muligvis er lækket. For et agentspecifikt endpoint kan du også bruge dashboardet: Åbn agentens sektion Webhooks, og vælg Regenerér hemmelighed på endpointet. Organisationsdækkende endpoints roteres via API'et.

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 '{}'

Returnerer 200 OK:

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

Send en testlevering#

Send en syntetisk webhook.test-hændelse til ét endpoint ved hjælp af den normale leveringspipeline, herunder kanonisk JSON-serialisering, begge signaturheadere, leveringsregistrering og håndtering af genforsøg. Testen målretter det valgte endpoint uanset dets events-filter.

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

Endepunktet modtager en indpakning som denne:

{
  "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 returnerer 200 OK efter det første forsøg, også hvis destinationen returnerer en fejl. Kontrollér success, status, response_code og error for leveringsresultatet:

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

webhook.test er syntetisk og kan ikke føjes til et endepunkts events- abonnement. Hvis det første forsøg mislykkes, prøver ThunderPhone igen én gang cirka et minut senere og stopper derefter; leveringen vises så med status: "failed" under Fejlfinding af leveringer. En testlevering markerer aldrig endepunktet som failing.

For at konfigurere en udløser mod en reel hændelsesform skal du angive en valgfri event_type. Leveringen er stadig syntetisk og indeholder "sample": true; opkaldsrelaterede eksempler bruger call_id: 0 og 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 accepterer enhver værdi fra Gyldige hændelsestyper. Hvis den udelades, bevares den generiske webhook.test-adfærd.

Slet et endepunkt#

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

Returnerer 204 No Content. Levering til URL'en stopper straks; igangværende genforsøg opgives.

Fejlfinding af leveringer#

Før du konkluderer, at en webhook ikke blev sendt, skal du kontrollere GET /v1/developer/webhook-deliveries. Den viser de seneste forsøg fra begge webhook-systemer, herunder opkalds-id, URL-oprindelse, HTTP-status, antal forsøg, fejlkategori på tilladelseslisten og tidspunktet for næste genforsøg. Den returnerer aldrig hændelsesdata, transskription, gemt fejltekst, svarbrødtekst eller URL-sti.

Du kan også se den samme seneste historik i Agenter → vælg en agent → Webhooks → Seneste leveringer. Rækker viser endepunktets etiket og den URL-oprindelse, der blev brugt ved det seneste forsøg. Dette er driftsstatus frem for en uforanderlig revisionslog: Sletning af et endepunkt sletter også dets leveringsrækker.

Ved en n8n-404 skal du først bekræfte, at workflowet er aktivt, accepterer POST og bruger produktions-webhook-URL'en i stedet for test-URL'en. En 401 eller 403 peger på godkendelse eller validering af signatur; timeouts peger på destinationsforsinkelse eller tilgængelighed; TLS-fejl peger på certifikatkæden, værtsnavnet eller udløb.

Relateret#