Webhook-slutpunkter - ThunderPhone

Det slutpunktbaserede webhook-system lader dig registrere flere destinationer pr. organisation, hver med sin egen hemmelighed, sin egen status og sit eget abonnement på et undersæt af hændelsestyper. Dette er den anbefalede model for alle nye integrationer. Sammenlign med den ældre webhook med én URL, som bevares af hensyn til bagudkompatibilitet, men kun understøtter én URL pr. organisation.

Slutpunkter

Metode	Sti	Påkrævet rolle	Beskrivelse
`GET`	`/v1/developer/webhook-endpoints`	`admin+`	Vis slutpunkter
`POST`	`/v1/developer/webhook-endpoints`	`admin+`	Opret et slutpunkt
`PATCH`	`/v1/developer/webhook-endpoints/{endpoint_id}`	`admin+`	Opdater etiket / URL / hændelser / status
`DELETE`	`/v1/developer/webhook-endpoints/{endpoint_id}`	`admin+`	Slet et slutpunkt
`POST`	`/v1/developer/webhook-endpoints/{endpoint_id}/test`	`admin+`	Send en signeret testlevering

Slutpunktsobjekt

{
  "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	Slutpunkts-id
`label`	string	Vist navn, 1–120 tegn
`url`	string	HTTPS-URL; `http://localhost` er tilladt til udvikling
`events`	array of string	Abonnerede hændelsestyper (se gyldige værdier). Et tomt array abonnerer på alle hændelser
`status`	string	`active`, `disabled` (manuelt sat på pause) eller `failing` (indstilles automatisk, når en levering opbruger sin 24 timers genforsøgsplan uden en eneste 2xx)
`secret_hint`	string	De første 4 og sidste 4 tegn i signeringshemmeligheden med en ellipse (`a1b2…9f0e`) — nok til at krydsreferere den hemmelighed, du har gemt lokalt, uden at afsløre hele værdien
`created_at`, `updated_at`	timestamp

Slutpunktets fulde secret returneres én gang ved oprettelse og aldrig igen. Gem den sikkert — hvis du mister den, skal du slette slutpunktet og oprette det igen.

Gyldige hændelsestyper

events valideres mod præcis dette sæt — værdier uden for listen returnerer 400. Se Hændelseskatalog for den enkelte types payload-format.

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

Slutpunktstatusser

active — leveringer forløber normalt.
disabled — manuelt sat på pause via PATCH. Der sendes ingen anmodninger. Vi ændrer aldrig status for et disabled slutpunkt; det er altid dit valg at ændre det tilbage til active.
failing — indstilles automatisk, når en levering til slutpunktet opbruger hele sin genforsøgsplan (8 forsøg over 24 timer) uden nogensinde at få en 2xx. Et fejlende slutpunkt modtager ingen yderligere trafik. Når slutpunktet er rettet, skal du PATCH dets status tilbage til active; leveringer, hvis genforsøgsplan endnu ikke er udløbet, fortsætter, hvor de slap.

Vis slutpunkter

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

Returnerer et array af slutpunktsobjekter.

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

Felt	Type	Påkrævet	Beskrivelse
`label`	streng	ja	1-120 tegn
`url`	streng	ja	HTTPS-URL (`http` er kun tilladt for `localhost` / `127.0.0.1`)
`events`	array	nej	Tom/udeladt abonnerer på alle hændelser. Skal bruge værdierne angivet i Gyldige hændelsestyper; dubletter fjernes

Returnerer 201 Created med det Endpoint-objekt plus et ekstra secret-felt på øverste niveau, der indeholder den rå signeringsnøgle - en hexstreng 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 kun ved oprettelse. Efterfølgende GET-svar indeholder kun secret_hint. Kopier hele værdien til din hemmelighedshåndtering, før du lukker svaret.

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

Felt	Type	Beskrivelse
`label`	streng
`url`	streng
`events`	array
`status`	streng	`active` eller `disabled`. Angiv `active` for at genaktivere et endpoint, som serveren har markeret som `failing`

Returnerer 200 OK med det opdaterede Endpoint-objekt.

Send en testlevering

Send en syntetisk webhook.test-hændelse til ét endpoint ved hjælp af den normale leveringspipeline, herunder kanonisk JSON-serialisering, X-ThunderPhone-Signature, registrering af leveringen 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"

Endpointet modtager en konvolut 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 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 endpoints events- abonnement. Hvis første forsøg fejler, følger leveringen samme genforsøgsplan som normale hændelsesleveringer.

Slet et endpoint

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.

Relateret

Hændelseskatalog

Den fulde liste over events-værdier, du kan abonnere på.

Webhooks-oversigt

Signaturverifikation og leveringssemantik.

​Slutpunkter

​Slutpunktsobjekt

​Gyldige hændelsestyper

​Slutpunktstatusser

​Vis slutpunkter

​Opret et endpoint

​Anmodningsfelter

​Opdater et endpoint

​Send en testlevering

​Slet et endpoint

​Relateret

Hændelseskatalog

Webhooks-oversigt

Slutpunkter

Slutpunktsobjekt

Gyldige hændelsestyper

Slutpunktstatusser

Vis slutpunkter

Opret et endpoint

Anmodningsfelter

Opdater et endpoint

Send en testlevering

Slet et endpoint

Relateret