Webhooks

Endpoints de webhook

Gerencie várias URLs de webhook com segredos por endpoint e filtros de eventos.

O sistema de webhooks baseado em endpoints permite registrar vários destinos por organização, cada um com seu próprio segredo, seu próprio status e sua própria assinatura para um subconjunto de tipos de evento. Este é o modelo recomendado para todas as novas integrações.

Compare com o webhook legado de URL única, que é mantido para compatibilidade com versões anteriores, mas suporta apenas uma URL por organização.

Endpoints#

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

Tipos de evento válidos#

events é validado em relação a este conjunto exato — valores fora da lista retornam 400. Consulte o catálogo de eventos para o formato do payload de cada 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

Status de endpoint#

• active — as entregas fluem normalmente.
• disabled — pausado manualmente via PATCH. Nenhuma solicitação é enviada. Nunca alteramos o status de um endpoint disabled; reverter para active é sempre sua decisão.
• failing — definido automaticamente quando uma entrega ao endpoint esgota toda a programação de tentativas (8 tentativas ao longo de 24 horas) sem receber um 2xx. Um endpoint com falha não recebe mais tráfego. Depois que o endpoint for corrigido, use PATCH para alterar seu status de volta para active; as entregas cuja programação de tentativas ainda não tiver terminado serão retomadas de onde pararam.

Listar endpoints#

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

Retorna um array de objetos de endpoint.

Criar um 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"]

Campos da solicitação#

Retorna 201 Created com o objeto Endpoint mais um campo extra secret no nível superior contendo a chave de assinatura bruta — uma string hexadecimal de 48 caracteres:

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

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

Retorna 200 OK com o objeto Endpoint atualizado.

Envie uma entrega de teste#

Envie um evento sintético webhook.test para um endpoint usando o pipeline normal de entrega, incluindo serialização JSON canônica, X-ThunderPhone-Signature, registro da entrega e controle de tentativas. O teste é direcionado ao endpoint selecionado independentemente do filtro events.

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

O endpoint recebe um envelope como:

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

A API retorna 200 OK após a primeira tentativa, mesmo que o destino retorne um erro. Inspecione success, status, response_code e error para verificar o resultado da entrega:

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

webhook.test é sintético e não pode ser adicionado à assinatura de events de um endpoint. Se a primeira tentativa falhar, a entrega seguirá a mesma programação de novas tentativas das entregas de eventos normais.

Exclua um endpoint#

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

Retorna 204 No Content. A entrega para a URL é interrompida imediatamente; as novas tentativas em andamento são abandonadas.

Relacionados#