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

# Webhooks do QSmartHub

> Receba eventos de senha, chamada e agendamento em tempo real: envelope, cadastro, entrega, retentativa e evento de teste.

Webhooks são como o QSmartHub avisa seu sistema de que algo mudou na operação, sem você precisar consultar a API. Como a v1 é de leitura, **webhooks são o canal para reagir a eventos**: uma senha nasce, é chamada, é finalizada, um agendamento muda de estado, e o QSmartHub faz um `POST` para a URL que você cadastrou.

## O envelope

Todo evento chega no corpo do `POST` com o mesmo envelope. O conteúdo específico do evento fica em `data`:

```json theme={null}
{
  "id": "evt_01JQ8Z3K7M9W0X1Y2Z3A4B5C6D",
  "type": "call.called",
  "version": "1",
  "created_at": "2026-11-16T14:32:05Z",
  "tenant_id": "01JQ8Z0A0A0A0A0A0A0A0A0A0A",
  "data": {
    "call_id": "01JQ8Z3K7M9W0X1Y2Z3A4B5C6D",
    "ticket_id": "01JQ8Z2B000000000000000000",
    "station_id": "01JQ8Z1C000000000000000000",
    "operator_id": "01JQ8Z1D000000000000000000"
  }
}
```

O `id` (`evt_...`) identifica a entrega de forma única. O `type` diz qual evento é. O `version` é sempre `"1"` nesta rodada. Datas em UTC com `Z`. Veja todos os tipos e seus campos em [Eventos](https://developers.qsmarthub.com/webhooks/eventos.md).

## Cadastrar um endpoint

No painel, em **Integrações › Webhooks**, informe a URL que vai receber os eventos e escolha quais eventos quer assinar. O QSmartHub gera um **segredo** por endpoint, usado para assinar cada entrega (veja [Segurança](https://developers.qsmarthub.com/webhooks/seguranca.md)).

> [!NOTE]
>
> Ao cadastrar, o QSmartHub envia um **ping de ativação**. O endpoint só fica ativo se responder `2xx` em até 10 segundos; senão fica `pending` até passar no teste.

> [!WARNING]
>
> A URL precisa ser **HTTPS** e pública. O QSmartHub recusa endereços internos ou privados (loopback, rede local). Veja os requisitos em [Segurança](https://developers.qsmarthub.com/webhooks/seguranca.md).

## Entrega

* **Pelo menos uma vez (at-least-once).** O mesmo evento pode chegar mais de uma vez. Use o `id` do envelope, enviado também no cabeçalho `X-QSmartHub-Delivery`, para **ignorar duplicatas** (idempotência).
* **Tempo limite de 10 segundos** por entrega. Responda `2xx` rapidamente e faça o trabalho pesado depois, numa fila sua.
* **Responda `2xx` para confirmar.** Qualquer outro status, ou tempo esgotado, conta como falha e entra na retentativa.

## Retentativa

Quando uma entrega falha, o QSmartHub repete em intervalos crescentes, até 6 tentativas no total:

| Tentativa | Quando |
| - | - |
| 1 | imediata |
| 2 | + 1 minuto |
| 3 | + 5 minutos |
| 4 | + 15 minutos |
| 5 | + 1 hora |
| 6 | + 6 horas |

Se todas as 6 falharem, o endpoint é **desativado** e o administrador da conta recebe um e-mail. Você pode reativar e reenviar entregas pelo painel.

## Testar

Na aba de webhooks você pode disparar um **evento de teste** para um endpoint e ver o código de resposta e o tempo na hora. Use-o para validar seu receptor antes de depender dele em produção.

## Próximos passos

> [card] [Eventos](https://developers.qsmarthub.com/webhooks/eventos.md)
>
> O catálogo completo: os 15 eventos e os campos que cada um carrega.

> [card] [Segurança](https://developers.qsmarthub.com/webhooks/seguranca.md)
>
> Como validar a assinatura HMAC e se proteger contra replay.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.