POST para a URL que você cadastrou.
O envelope
Todo evento chega no corpo doPOST com o mesmo envelope. O conteúdo específico do evento fica em data:
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.Entrega
- Pelo menos uma vez (at-least-once). O mesmo evento pode chegar mais de uma vez. Use o
iddo envelope, enviado também no cabeçalhoX-QSmartHub-Delivery, para ignorar duplicatas (idempotência). - Tempo limite de 10 segundos por entrega. Responda
2xxrapidamente e faça o trabalho pesado depois, numa fila sua. - Responda
2xxpara 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.