Weesy API Fiscal — Webhooks (1.0.0)

Um webhook é um aviso que a Weesy manda para o seu sistema quando algo acontece com uma nota — por exemplo, quando a prefeitura autoriza. Assim você não precisa ficar consultando.

Como funciona

1. Você informa um endereço (URL https) do seu sistema — veja Configurar o webhook da empresa.
2. Quando algo acontece, fazemos um POST nesse endereço com os dados da nota.
3. O seu sistema responde 200 (ou qualquer 2xx) em até 10 segundos. Responda rápido e processe depois: se demorar, consideramos que falhou.

Se o seu sistema não responder, tentamos de novo mais 6 vezes: 1 minuto depois da falha, depois 5 minutos, 30 minutos, 2 horas, 6 horas e 24 horas (cada espera conta a partir da tentativa anterior). São 7 tentativas no total, ao longo de cerca de 33 horas. Se todas falharem, o aviso fica como esgotado no histórico e você pode reenviá-lo quando quiser. Resposta de redirecionamento (3xx) conta como falha.

Três cuidados no seu sistema

• O mesmo aviso pode chegar mais de uma vez. Use o id do aviso para não processar duas vezes.
• A ordem pode trocar. Use ocorridoEm para saber o que aconteceu primeiro e, na dúvida, consulte a nota.
• Confira a assinatura. Todo aviso vem assinado pela Weesy; assim você tem certeza de que veio da gente e não foi alterado. O passo a passo, com código pronto, está no guia de webhooks.

Como conferir a assinatura, em resumo

Cada aviso traz três cabeçalhos: webhook-id, webhook-timestamp e webhook-signature.

1. Monte o texto <webhook-id>.<webhook-timestamp>.<corpo exatamente como chegou>.
2. Pegue a chave pública da Weesy em Obter as chaves para validar a assinatura (procure a chave pelo código que vem na assinatura — es256,<código da chave>,<assinatura>).
3. Verifique a assinatura com o algoritmo ES256 (ECDSA P-256 com SHA-256). As bibliotecas de criptografia do .NET, Node, PHP e Python fazem isso em poucas linhas.
4. Recuse avisos com webhook-timestamp de mais de 5 minutos atrás.

Atenção: as bibliotecas prontas de "Standard Webhooks" verificam outro algoritmo (HMAC) e não servem aqui — use os exemplos do guia.

Novos tipos de aviso podem aparecer. Se chegar um que o seu sistema não conhece, responda 200 e ignore.