Webhooks: receber eventos do app no seu sistema

Como criar um webhook, quais eventos existem, o que chega no corpo, como conferir a assinatura e o que acontece quando o destino falha.

Um webhook é uma URL sua que o App do MEI chama (POST com JSON) sempre que acontece um evento que você escolheu. Disponível nos planos Pro e Negócio, até 10 por negócio.

Criar

Em Mais → Integrações → Webhooks → Novo, dê um nome e cole a URL. Precisa ser https:// em um endereço público: localhost, IPs internos (10.x, 192.168.x) e afins são recusados.
Marque os eventos. Todos os eventos inclui os que forem criados no futuro.
Se o seu destino exige um token, adicione em Cabeçalhos extras (ex.: Authorization: Bearer …), um por linha.
Salve. Aparece o segredo whsec_… — copie na hora; ele não é mostrado de novo (dá para gerar outro em Gerar novo segredo).
Toque em Enviar teste: um evento ping vai para a URL e a entrega aparece na ficha com código, tempo e resposta.

Eventos

Contatos: criado, editado, mudou de etapa. Orçamentos: enviado, visualizado, aceito, recusado. Contratos: enviado, assinado, recusado. Cobranças: criada, paga, atrasada, cancelada. Agenda: compromisso criado, confirmado, cancelado, serviço concluído. Carteira: saque pago. Notas fiscais: NFS-e emitida. Os nomes técnicos (invoice.paid, quote.accepted…) aparecem ao lado de cada opção.

O que chega

Um JSON com event (o nome), created_at, account (id, uuid e nome do negócio) e data — o recurso completo no mesmo formato da API: número, status, valores em centavos, datas, link público, id do cliente. Você não precisa consultar nada depois.

Conferir a assinatura

Cada chamada leva o cabeçalho X-ADM-Signature: t=…,v1=…. v1 é o HMAC-SHA256 de t + "." + corpo com o seu segredo. Compare antes de processar e rejeite se t estiver a mais de 5 minutos do seu relógio. A ficha do webhook traz exemplos em PHP, Node e Python; a documentação completa está em /desenvolvedores.

Quando o destino falha

Qualquer resposta 2xx em até 10 segundos conta como entregue. Outra resposta, timeout ou redirecionamento agenda nova tentativa em 1 min, 5 min, 30 min, 2 h, 12 h e 24 h. Esgotadas, a entrega fica como desistida — você pode reenviar pela tela. Depois de 25 falhas seguidas o webhook é desativado e você recebe um aviso no app e por e-mail; corrija o destino, envie um teste e ative de novo.

Entregas

A ficha lista cada entrega com status, tentativa, código HTTP, tempo e erro. Abra uma para ver o payload enviado, os cabeçalhos e a resposta do seu servidor, e para Reenviar agora.

Dicas

Responda 200 primeiro e processe depois; trabalho demorado vira timeout.
A mesma entrega pode chegar mais de uma vez após uma falha: use o cabeçalho X-ADM-Delivery para não processar em dobro.
Pausar um webhook descarta os eventos do período — eles não ficam acumulados.
Excluir um webhook também excluir as entregas pendentes.