Endpoints de webhook

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 de 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 oferece suporte a apenas uma URL por organização.

Endpoints

Método	Caminho	Função obrigatória	Descrição
`GET`	`/v1/developer/webhook-endpoints`	`admin+`	Listar endpoints
`POST`	`/v1/developer/webhook-endpoints`	`admin+`	Criar um endpoint
`PATCH`	`/v1/developer/webhook-endpoints/{endpoint_id}`	`admin+`	Atualizar rótulo / URL / eventos / status
`DELETE`	`/v1/developer/webhook-endpoints/{endpoint_id}`	`admin+`	Excluir um endpoint
`POST`	`/v1/developer/webhook-endpoints/{endpoint_id}/test`	`admin+`	Enviar uma entrega de teste assinada

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

Campo	Tipo	Descrição
`id`	UUID	ID do endpoint
`label`	string	Nome de exibição, de 1 a 120 caracteres
`url`	string	URL HTTPS; `http://localhost` permitido para desenvolvimento
`events`	array de string	Tipos de evento assinados (consulte valores válidos). Um array vazio assina todos os eventos
`status`	string	`active`, `disabled` (pausado manualmente) ou `failing` (definido automaticamente quando uma entrega esgota sua programação de tentativas de 24 h sem um único 2xx)
`secret_hint`	string	Os primeiros 4 e os últimos 4 caracteres do segredo de assinatura com reticências (`a1b2…9f0e`) — o suficiente para conferir o segredo salvo localmente sem expor o valor completo
`created_at`, `updated_at`	timestamp

O secret completo do endpoint é retornado uma vez na criação e nunca mais. Armazene-o com segurança — se você o perder, exclua o endpoint e crie-o novamente.

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 ver o formato do payload de cada tipo.

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

Status dos endpoints

active — as entregas fluem normalmente.
disabled — pausado manualmente via PATCH. Nenhuma solicitação é enviada. Nunca alteramos o status de um endpoint disabled; voltar para active é sempre sua decisão.
failing — definido automaticamente quando uma entrega para o endpoint esgota toda a sua programação de tentativas (8 tentativas em 24 horas) sem receber um 2xx. Um endpoint com falha não recebe mais tráfego. Quando o endpoint for corrigido, use PATCH para alterar seu status de volta para active; as entregas cuja programação de tentativas ainda não terminou 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 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

Campo	Tipo	Obrigatório	Descrição
`label`	string	sim	1–120 caracteres
`url`	string	sim	URL HTTPS (`http` permitido apenas para `localhost` / `127.0.0.1`)
`events`	array	não	Vazio/omitido assina todos os eventos. Deve usar os valores listados em Tipos de evento válidos; duplicatas são removidas

Retorna 201 Created com o objeto Endpoint mais um campo secret adicional 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"
}

secret é retornado somente na criação. Respostas GET subsequentes incluem apenas secret_hint. Copie o valor completo para seu gerenciador de segredos antes de descartar a resposta.

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

Campo	Tipo	Descrição
`label`	string
`url`	string
`events`	array
`status`	string	`active` ou `disabled`. Defina como `active` para reativar um endpoint que o servidor marcou como `failing`

Retorna 200 OK com o objeto Endpoint atualizado.

Enviar 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 tem como destino o endpoint selecionado independentemente do filtro events dele.

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 este:

{
  "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 events de um endpoint. Se a primeira tentativa falhar, a entrega seguirá a mesma programação de tentativas das entregas de eventos normais.

Excluir 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 ao URL é interrompida imediatamente; as novas tentativas em andamento são abandonadas.

Relacionado

Catálogo de eventos

A lista completa de valores de events que você pode assinar.

Visão geral dos webhooks

Verificação de assinatura e semântica de entrega.

Webhooks

Function Tools

Endpoints

Objeto endpoint

Tipos de evento válidos

Status dos endpoints

Listar endpoints

Criar um endpoint

Campos da solicitação

Atualizar um endpoint

Enviar uma entrega de teste

Excluir um endpoint

Relacionado

Catálogo de eventos

Visão geral dos webhooks

​Endpoints

​Objeto endpoint

​Tipos de evento válidos

​Status dos endpoints

​Listar endpoints

​Criar um endpoint

​Campos da solicitação

​Atualizar um endpoint

​Enviar uma entrega de teste

​Excluir um endpoint

​Relacionado

Catálogo de eventos

Visão geral dos webhooks

Endpoints

Objeto endpoint

Tipos de evento válidos

Status dos endpoints

Listar endpoints

Criar um endpoint

Campos da solicitação

Atualizar um endpoint

Enviar uma entrega de teste

Excluir um endpoint

Relacionado