Webhooks

Webhook-slutpunkter

Hantera flera webhook-URL:er med hemligheter per slutpunkt och händelsefilter.

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 stöder en URL per organisation.

Slutpunkter#

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

Giltiga händelsetyper#

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

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

Slutpunktsstatusar#

• active — leveranser sker normalt.
• disabled — pausad manuellt via PATCH. Inga begäranden skickas. Vi ändrar aldrig statusen för en disabled slutpunkt; att ändra tillbaka den till active är alltid ditt beslut.
• failing — anges 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 ska du PATCH-uppdatera dess status 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 slutpunkt#

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#

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

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

Uppdatera en slutpunkt#

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

Returnerar 200 OK med det uppdaterade slutpunktsobjektet.

Skicka en testleverans#

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

{
  "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. Leveranser till URL:en stoppas omedelbart; pågående återförsök avbryts.

Relaterat#