Webhook-endepunkter

Administrer flere webhook-URL-er med hemmeligheter per endepunkt og hendelsesfiltre.

Det endepunktbaserte webhook-systemet lar deg registrere flere destinasjoner per organisasjon, hver med sin egen hemmelighet, sin egen status og sitt eget abonnement på et utvalg hendelsestyper. Dette er den anbefalte modellen for alle nye integrasjoner.

Sammenlign med eldre enkelt-URL-webhook, som beholdes for bakoverkompatibilitet, men bare støtter én URL per organisasjon.

Endepunkter#

Endepunktobjekt#

{
  "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 hendelsestyper#

events valideres mot nøyaktig dette settet — verdier utenfor listen returnerer 400. Se Hendelseskatalog for formen på nyttelasten til hver type.

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

issue.escalated har ingen stemmeagentkontekst og leveres bare til organisasjonsomfattende endepunkter.

voice.ready og voice.failed kan ikke velges eksplisitt. For å motta dem må du opprette et organisasjonsomfattende endepunkt med events: []. En tom hendelsesliste mottar alle støttede hendelser unntatt telephony.turn og web.turn, som må velges eksplisitt.

Endepunktstatuser#

• active — leveringer flyter normalt.
• disabled — satt på pause manuelt via PATCH. Ingen forespørsler sendes. Vi endrer aldri statusen til et disabled-endepunkt; det er alltid du som velger å sette det tilbake til active.
• failing — angis automatisk når en levering til endepunktet bruker opp hele forsøksplanen sin på nytt (8 forsøk over 24 timer) uten noen gang å få en 2xx. Et endepunkt med feil mottar ingen ytterligere trafikk. Vi sender e-post til organisasjonens eiere og administratorer når dette skjer, og dashbordet viser det pausede endepunktet med en Reaktiver-knapp. Når endepunktet er rettet, bruker du PATCH for å sette statusen tilbake til active; leveringer der forsøksplanen ennå ikke er utløpt, fortsetter der de slapp.

List opp endepunkter#

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

Returnerer en matrise med endepunktobjekter. Send ?agent_id=42 for å returnere bare endepunkter som er avgrenset til den stemmeagenten.

Endepunkter avgrenset til stemmeagent#

Organisasjonsomfattende endepunkter mottar alle samsvarende hendelser. Et endepunkt med agent_id mottar bare samsvarende hendelser for samtaler håndtert av den stemmeagenten; hendelser uten stemmeagentkontekst, som alert.triggered, når det aldri. Du kan også opprette og administrere disse endepunktene fra stemmeagentbyggerens seksjon Webhooks.

Opprett et endepunkt#

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

Forespørselsfelt#

Returnerer 201 Created med endepunktobjektet pluss et ekstra secret-felt på øverste nivå som inneholder den rå signeringsnøkkelen — en 48-tegns heksadesimal streng:

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

Oppdater et endepunkt#

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 oppdaterte endepunktobjektet.

Roter signeringshemmeligheten#

Erstatt et endepunkts signeringshemmelighet, for eksempel når den er mistet eller kan ha blitt lekket. For et agentavgrenset endepunkt kan du også bruke dashbordet: Åpne agentens Webhooker-seksjon og velg Regenerer hemmelighet på endepunktet. Organisasjonsomfattende endepunkter 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-hendelse til ett endepunkt ved hjelp av den vanlige leveringsprosessen, inkludert kanonisk JSON-serialisering, begge signaturhodene, leveringslogging og registrering av nye forsøk. Testen retter seg mot det valgte endepunktet uavhengig av events-filteret.

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

Endepunktet mottar en konvolutt 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 etter første forsøk, selv om destinasjonen returnerer en feil. Kontroller 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 legges til i et endepunkts events- abonnement. Hvis første forsøk mislykkes, prøver ThunderPhone på nytt én gang omtrent ett minutt senere og stopper deretter. Leveringen viser da status: "failed" under Feilsøk leveringer. En testlevering markerer aldri endepunktet som failing.

For å konfigurere en utløser mot en ekte hendelsesstruktur, kan du sende et valgfritt event_type. Leveringen er fortsatt syntetisk og inneholder "sample": true; anropsrelaterte eksempler bruker 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 godtar enhver verdi fra Gyldige hendelsestyper. Hvis du utelater det, beholdes den generiske webhook.test-atferden.

Slett 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 umiddelbart; pågående nye forsøk avbrytes.

Feilsøk leveringer#

Før du konkluderer med at en webhook ikke ble sendt, bør du kontrollere GET /v1/developer/webhook-deliveries. Den viser nylige forsøk fra begge webhook-systemene, inkludert anrops-ID, URL-opprinnelse, HTTP-status, antall forsøk, tillatt feilkategori og tidspunkt for neste forsøk. Den returnerer aldri hendelsesnyttelasten, transkripsjonen, lagret feiltekst, svartekst eller URL-bane.

Du kan også se den samme nylige historikken i Agenter → velg en agent → Webhooks → Nylige leveringer. Radene viser endepunktetiketten og URL-opprinnelsen som ble brukt i det siste forsøket. Dette er driftsstatus, ikke en uforanderlig revisjonslogg: Hvis du sletter et endepunkt, slettes også leveringsradene.

Ved en n8n-404 må du først bekrefte at arbeidsflyten er aktiv, godtar POST og bruker produksjonswebhook-URL-en i stedet for test-URL-en. En 401 eller 403 peker på autentisering eller signaturvalidering; tidsavbrudd peker på forsinkelse eller tilgjengelighet hos destinasjonen; TLS-feil peker på sertifikatkjeden, vertsnavnet eller utløpsdatoen.

Relatert#