Skip to main content
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:
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.

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).
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.
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.

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

Eventos

O catálogo completo: os 15 eventos e os campos que cada um carrega.

Segurança

Como validar a assinatura HMAC e se proteger contra replay.