Funcionamento dos Webhooks iPag

Este artigo descreve como funciona o disparo de webhooks pela plataforma iPag, quais práticas recomendamos aos clientes que irão consumi-los e como lidar com possíveis falhas ou exceções.

Como funcionam os disparos

Sempre que um evento relevante ocorre (ex.: atualização de status de transação), o iPag envia uma requisição HTTP POST para a URL configurada pelo cliente.

• Formato da mensagem: JSON

• Método: POST

• Headers padrão:

  • Content-Type: application/json

  • Assinatura de segurança (quando aplicável)

• Timeout de conexão (timeout_connect): 2 segundos

• Timeout de resposta (timeout): 5 segundos na primeira tentativa

Política de Timeouts e Retentativas

Para garantir a entrega mesmo em situações de indisponibilidade temporária do cliente, aplicamos a seguinte lógica:

1. Primeira tentativa: timeout de 5 segundos

2. Segunda tentativa (após 5 minutos): timeout de 10 segundos

3. Terceira tentativa (após mais 15 minutos): timeout de 20 segundos

Caso todas as tentativas falhem, o evento é marcado como não entregue.

Indicadores de entrega (exemplo real)

Em um período recente, tivemos o seguinte cenário de 2.422 envios:

• 96,12% entregues com sucesso na primeira tentativa

• 3,47% marcaram timeout (408), mas 100% foram entregues nas retentativas

• 0,41% foram bloqueados por Rate Limiting (429); destes, apenas 1 envio (0,04%) não pôde ser entregue mesmo após as novas tentativas

Esse resultado mostra que o mecanismo de retentativas garante alta confiabilidade, mesmo em casos de instabilidade temporária.

Recomendações para os clientes que recebem webhooks

Para que os webhooks funcionem da forma mais estável possível, recomendamos:

1. Resposta rápida

   • Retorne 200 OK assim que possível.

   • Se for necessário processamento adicional, faça de forma assíncrona.

   • Evite que a resposta dependa de integrações externas lentas.

2. Alta disponibilidade da API

   • A URL de recebimento deve estar sempre acessível.

   • Configure balanceamento de carga e redundância quando possível.

3. Evite bloqueios por Rate Limiting

   • Permita tráfego contínuo do iPag sem restrições agressivas.

   • Se aplicar limites, ajuste-os para suportar o volume de webhooks esperado.

4. Segurança

   • Valide a assinatura (quando disponível).

   • Restrinja o recebimento de chamadas à origem do iPag.

   • Utilize HTTPS com certificado válido.

5. Logs e monitoramento

   • Registre tanto o recebimento quanto a resposta enviada.

   • Monitore tempos de resposta para identificar gargalos.

Possíveis causas de timeout no cliente

Mesmo que o sistema do cliente registre a geração da resposta, podem ocorrer delays que levam ao timeout no iPag, como:

• Latência de rede ou congestionamento de saída

• Proxies, balanceadores ou firewalls introduzindo atraso

• Sobrecarga momentânea do servidor

Nesses casos, embora o cliente veja que a resposta foi produzida, ela pode não ter chegado ao iPag dentro do limite configurado.

Conclusão

O sistema de webhooks do iPag foi projetado para ser rápido, resiliente e confiável, com política de retentativas progressivas que assegura a entrega em praticamente todos os cenários.

Seguindo as boas práticas acima, os clientes conseguem garantir que os eventos sejam recebidos sem falhas e sem comprometer o desempenho de seus sistemas.

Documentação técnica: https://developers.ipag.com.br/pt-br/webhook?id=introdu%c3%a7%c3%a3o