Leonardo Peron5 min de leitura
A pergunta aparece na primeira reunião de qualquer integração e costuma ser decidida pelo que o fornecedor oferece: se tem webhook, usa webhook; se não tem, consulta de tempos em tempos. Escolher por disponibilidade esconde que os dois mecanismos garantem coisas diferentes — e que a maior parte das operações precisa das duas garantias.
O que cada um garante
O webhook entrega rápido e cobra pouco: só há tráfego quando algo acontece. O que ele não oferece é evidência de entrega do lado de quem recebe. Quando o aviso não chega, não acontece nada — e "não aconteceu nada" é indistinguível de "não havia nada para avisar". A falha é silêncio, e silêncio não dispara alarme nenhum.
A consulta periódica gasta requisição mesmo quando nada mudou e entrega com o atraso da janela. Em troca, tem uma propriedade que o webhook não tem: uma varredura futura enxerga o que a anterior não enxergou. Nada depende de uma única tentativa ter dado certo.
São qualidades diferentes, não graus da mesma qualidade. Uma é latência; a outra é garantia.
Onde o webhook perde evento
Vale conhecer os casos, porque nenhum deles aparece como erro.
O endereço ficou fora do ar durante um deploy. Alguns provedores repetem por um tempo, outros tentam uma vez e desistem, e esse comportamento raramente está na mesma página da documentação que descreve o formato.
A resposta demorou. O provedor considerou a entrega falha e, a partir daí, ou reenvia — e você precisa aguentar a repetição sem duplicar — ou desiste.
A assinatura foi desligada sem ninguém perceber. Mudança de ambiente, alguém mexendo no painel, troca de credencial: o cadastro do endereço some e não há aviso, porque do ponto de vista do fornecedor nada quebrou.
A ordem chegou trocada. O aviso de cancelamento chega antes do de pagamento e o estado final fica errado. Ordem de entrega é uma garantia que quase nenhum provedor dá e que quase toda integração assume.
Onde a consulta periódica perde
Ela também não é a alternativa segura por natureza.
A janela é o piso da latência: consultar a cada quinze minutos significa dado com até quinze minutos de idade, e isso precisa caber na operação antes de qualquer outra discussão.
A cota é consumida perguntando por nada. Em fornecedor com limite de requisições apertado, a varredura frequente compete com o que é urgente.
E o filtro "alterado desde" depende de semântica que é do outro lado, não sua. Alteração feita por rotina interna do fornecedor pode não atualizar o campo de data. Registro que muda no meio da sua paginação pode aparecer duas vezes ou nenhuma. São detalhes chatos que só aparecem quando alguém compara totais.
O arranjo que funciona
Webhook para latência, varredura para garantia. O webhook é o caminho rápido; a varredura é a que diz a verdade.
O que torna esse arranjo barato é uma condição: as duas entradas desembocam no mesmo ponto, e esse ponto precisa ser idempotente. A varredura vai trazer de novo, todo dia, o que o webhook já trouxe. Se isso não for uma operação sem efeito, a rede de segurança vira uma máquina de duplicar registro, e o remédio fica pior que a doença.
Resolvida a idempotência, a varredura deixa de ser escolha e passa a ser apólice barata: roda, quase sempre não encontra nada novo, e no dia em que o webhook falhar é a razão de ninguém descobrir pelo cliente.
Dimensionar a janela
A varredura precisa olhar para trás por mais tempo do que o intervalo em que ela roda. Rodar a cada dez minutos perguntando pelos últimos dez é o erro que anula o mecanismo: o que mudou exatamente na borda cai entre duas execuções.
A sobreposição existe por três razões concretas. Os relógios dos dois lados não são o mesmo. Um registro em transação no momento da varredura anterior só ficou visível depois. E há fornecedor cuja listagem demora a refletir o que a consulta individual já mostra.
Quanto de sobreposição é medida, não palpite: o maior atraso já observado entre o fato acontecer no outro lado e ele aparecer na listagem. Comece generoso, meça e reduza com evidência.
Acima dessa, vale uma varredura mais larga e mais rara — diária, sobre um período longo, comparando quantidade em vez de só trazer registro. É a mesma ideia da reconciliação: não confiar que nada se perdeu, e sim conferir.
O número que justifica manter os dois
Uma contagem responde se o arranjo está valendo: quantos registros a varredura encontrou que o webhook nunca entregou.
Zero por semanas seguidas diz que o caminho rápido está saudável, e talvez dê para espaçar a varredura. Um número que cresce diz que o webhook está degradando — informação que ninguém teria de outro jeito, porque webhook que não chega não reclama.
O teste que confirma
Devolva erro no seu endereço de webhook, de propósito, por meia hora, enquanto o outro lado gera eventos. Depois volte ao normal e não reprocesse nada à mão.
O certo é a varredura trazer tudo sozinha, dentro de uma janela, uma vez cada. Depois olhe o contador de registros que vieram pela varredura e não pelo webhook. Se ele não existe, ter descoberto isso já foi o resultado do teste.