> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 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](/api-reference/organizations#legacy-single-url-webhook),
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

```json theme={null}
{
  "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](#valid-event-types)). 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       |                                                                                                                                                                                    |

<Note>
  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.
</Note>

### 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](/pt/webhooks/events) 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

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.thunderphone.com/v1/developer/webhook-endpoints \
    -H "Authorization: Bearer sk_live_YOUR_API_KEY"
  ```
</CodeGroup>

Retorna um array de [objetos Endpoint](#endpoint-object).

***

## Criar um endpoint

<CodeGroup>
  ```bash cURL theme={null}
  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"]
    }'
  ```

  ```python Python theme={null}
  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"]
  ```
</CodeGroup>

### 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](#valid-event-types); duplicatas são removidas |

Retorna `201 Created` com o [objeto Endpoint](#endpoint-object) mais
um campo `secret` adicional no nível superior contendo a chave de assinatura bruta — uma
string hexadecimal de 48 caracteres:

```json theme={null}
{
  "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"
}
```

<Warning>
  `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.
</Warning>

***

## Atualizar um endpoint

<CodeGroup>
  ```bash cURL theme={null}
  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"]
    }'
  ```
</CodeGroup>

| 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](#endpoint-object) 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.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
    -H "Authorization: Bearer sk_live_YOUR_API_KEY"
  ```
</CodeGroup>

O endpoint recebe um envelope como este:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
    -H "Authorization: Bearer sk_live_YOUR_API_KEY"
  ```
</CodeGroup>

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

***

## Relacionado

<CardGroup cols={2}>
  <Card title="Catálogo de eventos" icon="list" href="/pt/webhooks/events">
    A lista completa de valores de `events` que você pode assinar.
  </Card>

  <Card title="Visão geral dos webhooks" icon="bolt" href="/pt/webhooks/overview">
    Verificação de assinatura e semântica de entrega.
  </Card>
</CardGroup>