Webhook-endepunkter

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 av hendelsestyper. Dette er den anbefalte modellen for alle nye integrasjoner. Sammenlign med den eldre webhooken med én URL, som beholdes for bakoverkompatibilitet, men bare støtter én URL per organisasjon.

Endepunkter

Metode	Bane	Påkrevd rolle	Beskrivelse
`GET`	`/v1/developer/webhook-endpoints`	`admin+`	List opp endepunkter
`POST`	`/v1/developer/webhook-endpoints`	`admin+`	Opprett et endepunkt
`PATCH`	`/v1/developer/webhook-endpoints/{endpoint_id}`	`admin+`	Oppdater etikett / URL / hendelser / status
`DELETE`	`/v1/developer/webhook-endpoints/{endpoint_id}`	`admin+`	Slett et endepunkt
`POST`	`/v1/developer/webhook-endpoints/{endpoint_id}/test`	`admin+`	Send en signert testlevering

Endepunktobjekt

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

Felt	Type	Beskrivelse
`id`	UUID	Endepunkt-ID
`label`	string	Visningsnavn, 1–120 tegn
`url`	string	HTTPS-URL; `http://localhost` er tillatt for utvikling
`events`	array of string	Abonnerte hendelsestyper (se gyldige verdier). Tom matrise abonnerer på alle hendelser
`status`	string	`active`, `disabled` (pauset manuelt) eller `failing` (settes automatisk når en levering bruker opp sin 24-timers gjenoppslagsplan uten én eneste 2xx)
`secret_hint`	string	De første 4 og siste 4 tegnene i signeringshemmeligheten med en ellipse (`a1b2…9f0e`) — nok til å kryssreferere hemmeligheten du lagret lokalt uten å eksponere hele verdien
`created_at`, `updated_at`	timestamp

Endepunktets fullstendige secret returneres én gang ved opprettelse og aldri igjen. Lagre den sikkert — hvis du mister den, slett endepunktet og opprett det på nytt.

Gyldige hendelsestyper

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

telephony.incoming, telephony.complete, telephony.tool
web.incoming, web.complete, web.tool
call.graded
issue.reported
test-call.completed
alert.triggered

Endepunktstatuser

active — leveringer flyter normalt.
disabled — pauset manuelt via PATCH. Ingen forespørsler sendes. Vi endrer aldri statusen til et disabled-endepunkt; å sette det tilbake til active er alltid ditt valg.
failing — settes automatisk når en levering til endepunktet bruker opp hele gjenoppslagsplanen (8 forsøk over 24 timer) uten noen gang å få en 2xx. Et feilende endepunkt mottar ikke mer trafikk. Når endepunktet er rettet, bruk PATCH for å sette statusen tilbake til active; leveringer der gjenoppslagsplanen 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.

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

Felt	Type	Påkrevd	Beskrivelse
`label`	string	ja	1–120 tegn
`url`	string	ja	HTTPS-URL (`http` er bare tillatt for `localhost` / `127.0.0.1`)
`events`	array	nei	Tomt/utelatt abonnerer på alle hendelser. Må bruke verdiene som er oppført i Gyldige hendelsestyper; duplikater fjernes

Returnerer 201 Created med det endepunktobjektet pluss et ekstra secret-felt på toppnivå som inneholder den rå signeringsnøkkelen — en heksadesimal 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"
}

secret returneres bare ved opprettelse. Etterfølgende GET-svar inkluderer bare secret_hint. Kopier hele verdien til hemmelighetshåndteringssystemet før du lukker svaret.

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

Felt	Type	Beskrivelse
`label`	string
`url`	string
`events`	array
`status`	string	`active` eller `disabled`. Angi `active` for å aktivere et endepunkt på nytt når serveren har merket det som `failing`

Returnerer 200 OK med det oppdaterte endepunktobjektet.

Send en testlevering

Send en syntetisk webhook.test-hendelse til ett endepunkt via den vanlige leveringspipelinen, inkludert kanonisk JSON-serialisering, X-ThunderPhone-Signature, leveringsregistrering og håndtering 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, følger leveringen samme plan for nye forsøk som vanlige hendelsesleveringer.

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.

Relatert

Hendelseskatalog

Den fullstendige listen over events-verdier du kan abonnere på.

Oversikt over webhooks

Signaturverifisering og leveringssemantikk.

Webhooks

Function Tools

Endepunkter

Endepunktobjekt

Gyldige hendelsestyper

Endepunktstatuser

List opp endepunkter

Opprett et endepunkt

Forespørselsfelt

Oppdater et endepunkt

Send en testlevering

Slett et endepunkt

Relatert

Hendelseskatalog

Oversikt over webhooks

​Endepunkter

​Endepunktobjekt

​Gyldige hendelsestyper

​Endepunktstatuser

​List opp endepunkter

​Opprett et endepunkt

​Forespørselsfelt

​Oppdater et endepunkt

​Send en testlevering

​Slett et endepunkt

​Relatert

Hendelseskatalog

Oversikt over webhooks

Endepunkter

Endepunktobjekt

Gyldige hendelsestyper

Endepunktstatuser

List opp endepunkter

Opprett et endepunkt

Forespørselsfelt

Oppdater et endepunkt

Send en testlevering

Slett et endepunkt

Relatert