Os webhooks permitem receber avisos do serviço sem depender apenas de consultas periódicas. Numa API Verifactu, devem fazer parte do acompanhamento das operações: receber um evento, identificar o documento e decidir a atualização adequada. O recetor também precisa de um plano para eventos repetidos ou inesperados.
Comece pelos tipos disponíveis
A referência da nossa API inclui operações para consultar tipos de webhook, configurar uma URL e consultar os webhooks registados. Reveja-as antes de criar o recetor. Confirme com a equipa o formato exato do aviso e o mecanismo de autenticação; não invente uma assinatura, um cabeçalho ou uma garantia de entrega que o contrato não especifique.
Relacione cada aviso com uma operação
Conserve os identificadores devolvidos pelos envios e use-os para ligar o resultado ao documento local. A documentação inclui consultas de envios identificados por queueId. Mantenha esta referência técnica separada do número comercial da fatura para evitar associações ambíguas, sobretudo quando gere várias empresas.
Torne segura a repetição de avisos
Desenhe a atualização de estado para que processar o mesmo evento duas vezes não duplique ações. Verifique o estado persistido antes de enviar mensagens ou iniciar tarefas posteriores. Não presuma que os avisos chegam na ordem esperada pela interface; em caso de dúvida, compare a informação com as consultas disponíveis e evite substituir um resultado conhecido por outro antigo.
- Valide a autenticação e a estrutura recebida.
- Confirme a empresa e o documento do evento.
- Registe uma referência útil para analisar incidências.
- Teste duplicados, atrasos e erros temporários do recetor.
Mantenha uma via de reconciliação
Um webhook não elimina a necessidade de rever operações cujo estado local ficou desatualizado. Defina uma reconciliação que respeite os limites do serviço e uma fila de incidências para a equipa. Assim poderá recuperar o acompanhamento após uma interrupção sem envios repetidos nem alterações manuais sem rastreabilidade.