Webhooks

Endpoint webhook

Gestisci più URL webhook con segreti e filtri eventi per endpoint.

Il sistema di webhook basato su endpoint ti consente di registrare più destinazioni per organizzazione, ciascuna con il proprio segreto, il proprio stato e la propria sottoscrizione a un sottoinsieme di tipi di evento. Questo è il modello consigliato per tutte le nuove integrazioni.

Confrontalo con il webhook legacy a URL singolo, mantenuto per la compatibilità con le versioni precedenti ma che supporta un solo URL per organizzazione.

Endpoint#

Oggetto endpoint#

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

Tipi di evento validi#

events viene convalidato rispetto a questo insieme esatto — i valori al di fuori dell'elenco restituiscono 400. Consulta il catalogo degli eventi per la struttura del payload di ciascun tipo.

• 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

Stati dell'endpoint#

• active — le consegne avvengono normalmente.
• disabled — messo in pausa manualmente tramite PATCH. Non viene inviata alcuna richiesta. Non modifichiamo mai lo stato di un endpoint disabled; riportarlo a active dipende sempre da te.
• failing — impostato automaticamente quando una consegna all'endpoint esaurisce l'intero programma di tentativi (8 tentativi in 24 ore) senza mai ottenere un 2xx. Un endpoint in stato failing non riceve ulteriore traffico. Dopo aver corretto l'endpoint, usa PATCH per riportarne lo stato a active; le consegne il cui programma di tentativi non è ancora esaurito riprendono dal punto in cui si erano fermate.

Elenca gli endpoint#

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

Restituisce un array di oggetti endpoint.

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

Campi della richiesta#

Restituisce 201 Created con l'oggetto Endpoint aggiornato più un campo secret aggiuntivo di primo livello contenente la chiave di firma non elaborata: una stringa esadecimale di 48 caratteri:

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

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

Restituisce 200 OK con l'oggetto Endpoint aggiornato.

Invia una consegna di test#

Invia un evento sintetico webhook.test a un endpoint usando la normale pipeline di consegna, inclusi la serializzazione JSON canonica, X-ThunderPhone-Signature, la registrazione della consegna e la gestione dei tentativi. Il test è indirizzato all'endpoint selezionato indipendentemente dal relativo filtro events.

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

L'endpoint riceve un envelope come questo:

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

L'API restituisce 200 OK dopo il primo tentativo, anche se la destinazione restituisce un errore. Controlla success, status, response_code ed error per conoscere l'esito della consegna:

{
  "success": true,
  "event_id": "2ad6507c-7d19-4498-9b2d-7e8f944ab5a1",
  "event_type": "webhook.test",
  "status": "delivered",
  "response_code": 204,
  "error": ""
}

webhook.test è sintetico e non può essere aggiunto all'iscrizione events di un endpoint. Se il primo tentativo non riesce, la consegna segue la stessa pianificazione dei tentativi delle normali consegne di eventi.

Elimina un endpoint#

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

Restituisce 204 No Content. La consegna all'URL si interrompe immediatamente; i nuovi tentativi già in corso vengono abbandonati.

Correlati#