Webhook-slutpunkter

Det slutpunktsbaserade webhooksystemet 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 bara har stöd för en URL per organisation.

Slutpunkter

Metod	Sökväg	Krävd roll	Beskrivning
`GET`	`/v1/developer/webhook-endpoints`	`admin+`	Lista slutpunkter
`POST`	`/v1/developer/webhook-endpoints`	`admin+`	Skapa en slutpunkt
`PATCH`	`/v1/developer/webhook-endpoints/{endpoint_id}`	`admin+`	Uppdatera etikett / URL / händelser / status
`DELETE`	`/v1/developer/webhook-endpoints/{endpoint_id}`	`admin+`	Ta bort en slutpunkt
`POST`	`/v1/developer/webhook-endpoints/{endpoint_id}/test`	`admin+`	Skicka en signerad testleverans

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

Fält	Typ	Beskrivning
`id`	UUID	Slutpunkts-id
`label`	string	Visningsnamn, 1–120 tecken
`url`	string	HTTPS-URL; `http://localhost` tillåts för utveckling
`events`	array of string	Prenumererade händelsetyper (se giltiga värden). En tom array prenumererar på alla händelser
`status`	string	`active`, `disabled` (manuellt pausad) eller `failing` (ställs in automatiskt när en leverans förbrukar sitt återförsöksschema på 24 h utan en enda 2xx)
`secret_hint`	string	De första 4 och sista 4 tecknen i signeringshemligheten med en ellips (`a1b2…9f0e`) — tillräckligt för att jämföra med hemligheten du sparade lokalt utan att exponera hela värdet
`created_at`, `updated_at`	timestamp

Slutpunktens fullständiga secret returneras en gång när den skapas och aldrig igen. Spara den säkert — om du förlorar den måste du ta bort slutpunkten och skapa den igen.

Giltiga händelsetyper

events valideras mot exakt denna uppsättning — värden utanför listan returnerar 400. Se händelsekatalogen för varje typs payloadformat.

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

Slutpunktsstatusar

active — leveranser fungerar normalt.
disabled — manuellt pausad via PATCH. Inga förfrågningar skickas. Vi ändrar aldrig statusen för en disabled slutpunkt; att ändra den tillbaka till active är alltid ditt beslut.
failing — ställs in automatiskt när en leverans till slutpunkten förbrukar hela sitt återförsöksschema (8 försök under 24 timmar) utan att någonsin få en 2xx. En felande slutpunkt tar inte emot någon ytterligare trafik. När slutpunkten har åtgärdats använder du PATCH för att ändra dess status 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.

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

Begärandefält

Fält	Typ	Obligatoriskt	Beskrivning
`label`	string	ja	1–120 tecken
`url`	string	ja	HTTPS-URL (`http` tillåts endast för `localhost` / `127.0.0.1`)
`events`	array	nej	Tomt/utelämnat prenumererar på alla händelser. Måste använda värdena som listas i Giltiga händelsetyper; dubbletter tas bort

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

{
  "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 returneras endast vid skapande. Efterföljande GET-svar innehåller endast secret_hint. Kopiera hela värdet till din hemlighetshanterare innan du avfärdar svaret.

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

Fält	Typ	Beskrivning
`label`	string
`url`	string
`events`	array
`status`	string	`active` eller `disabled`. Ange `active` för att återaktivera en endpoint som servern har markerat som `failing`

Returnerar 200 OK med det uppdaterade endpointobjektet.

Skicka en testleverans

Skicka en syntetisk webhook.test-händelse till en endpoint med den vanliga leveransprocessen, inklusive kanonisk JSON-serialisering, X-ThunderPhone-Signature, 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"

Endpointen tar emot ett kuvert som:

{
  "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:t 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 endpoints events- prenumeration. Om det första försöket misslyckas följer leveransen samma schema för återförsök som vanliga händelseleveranser.

Ta bort en endpoint

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

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

Relaterat

Händelsekatalog

Den fullständiga listan över events-värden som du kan prenumerera på.

Översikt över webhooks

Signaturverifiering och leveranssemantik.

Webhooks

Function Tools

Slutpunkter

Slutpunktsobjekt

Giltiga händelsetyper

Slutpunktsstatusar

Lista slutpunkter

Skapa en endpoint

Begärandefält

Uppdatera en endpoint

Skicka en testleverans

Ta bort en endpoint

Relaterat

Händelsekatalog

Översikt över webhooks

​Slutpunkter

​Slutpunktsobjekt

​Giltiga händelsetyper

​Slutpunktsstatusar

​Lista slutpunkter

​Skapa en endpoint

​Begärandefält

​Uppdatera en endpoint

​Skicka en testleverans

​Ta bort en endpoint

​Relaterat

Händelsekatalog

Översikt över webhooks

Slutpunkter

Slutpunktsobjekt

Giltiga händelsetyper

Slutpunktsstatusar

Lista slutpunkter

Skapa en endpoint

Begärandefält

Uppdatera en endpoint

Skicka en testleverans

Ta bort en endpoint

Relaterat