Webhooks da API: avisar o seu outro sistema quando uma venda, nota, conta ou cliente muda

O webhook é o sistema avisando o seu outro sistema na hora em que algo muda: uma venda, uma nota autorizada, um recebimento baixado. Em vez de o seu sistema consultar a API de tempos em tempos, ele recebe o aviso assim que acontece.

Onde fica

Meus aplicativos › Ver todos os aplicativos › API (botão Acessar). Na tela inicial do aplicativo, clique no cartão Webhooks.

Só o usuário administrador (master) da conta cadastra webhooks, e o recurso faz parte da integração via API do seu plano.

Cadastrar um endereço

1. Clique em Adicionar endereço.
2. Em Para onde mandar os avisos, informe o endereço do seu sistema que vai receber (por exemplo, https://seu-sistema.com.br/webhooks). Só endereço público com https é aceito.
3. Se quiser, marque Receber de uma loja só e escolha a loja.
4. Em O que avisar, escolha Todos os eventos, inclusive os que vierem depois ou Só os que você marcar.
5. Clique em Salvar. Aparece o Segredo: copie agora. Ele serve para o seu sistema conferir que o aviso veio daqui e não aparece de novo. Se perder, use Gerar segredo novo (o anterior deixa de valer na hora).

Dá para cadastrar até 5 endereços. Em cada um, as ações são Enviar teste, Pausar ou Reativar, Gerar segredo novo, Editar, Entregas e Excluir.

O que é avisado

| Grupo | Evento |
|---|---|
| Vendas e serviços | Venda cadastrada; Situação da venda mudou; Situação do orçamento mudou; Situação da OS mudou |
| Notas fiscais | Nota autorizada; Nota cancelada (NF-e, NFC-e e NFS-e) |
| Financeiro | Recebimento baixado; Pagamento baixado |
| Cadastros | Cliente cadastrado; Cliente alterado |

O aviso traz o essencial do que aconteceu: o tipo do evento, o registro, a loja, quem fez e quando. Para ver o registro completo, o seu sistema consulta a API com a chave dele. O aviso diz também de onde veio a mudança (tela, API, PDV, loja virtual ou automação), para o seu sistema ignorar o que ele mesmo fez.

Entregas, reenvio e pausa

Em Entregas você vê os avisos dos últimos 30 dias: o evento, a situação, a resposta do seu sistema e o detalhe de cada um, com o botão Reenviar.

  • O aviso conta como entregue quando o seu sistema responde com sucesso em até 5 segundos.
  • Se falhar, o sistema tenta de novo: são 8 tentativas, ao longo de cerca de 2 dias. Depois disso, a entrega aparece como "Desistiu depois de 8 tentativas".
  • Endereço que falha em todas as entregas por 3 dias é pausado sozinho, e o administrador recebe um e-mail. Depois de corrigir o seu sistema, clique em Reativar.

Para quem programa

Na documentação da API, a aba Webhooks explica o formato do aviso, como conferir a assinatura (cabeçalho X-Webhook-Assinatura) e as boas práticas:

  • Responda primeiro e processe depois.
  • O mesmo aviso pode chegar duas vezes numa falha de rede: guarde o identificador e descarte o repetido.
  • A ordem pode variar: use a data do evento ou consulte o registro na API.
  • Se o seu sistema ficou fora do ar por mais tempo que as tentativas, consulte as listagens da API para pôr em dia o que mudou.