Webhook

1. Visão Geral

A implementação do Webhook moderniza a arquitetura da sua integração, substituindo o modelo de consultas recorrentes (polling) por notificações ativas. Isso garante atualizações em tempo real e elimina a necessidade de chamadas constantes aos seguintes endpoints:

• /proposals/**:proposalId**/status
• /proposals/**:proposalId**/conditions/credit-approved
• /proposals/**:proposalId**/conditions/payment-approved

2. Como Funciona a Implementação

2.1. Pré-requisitos técnicos

• Protocolo: Seus endpoints devem utilizar HTTPS com certificados SSL ou TLS válidos.
• Método: Nossos eventos são enviados sempre utilizando o método HTTP POST.

2.2. Passo a Passo de Configuração

1. Solicitação de Registro: Entre em contato com seu consultor para registrar sua aplicação. Você precisará informar:
   1. Quais eventos deseja assinar (todos ou específicos).
   2. A URL (endpoint) de destino para as notificações de Produção.
2. Homologação: Para validar a integração, informe também uma URL específica para receber os eventos do nosso ambiente de Homologação.
3. Credenciais: Após o registro, solicite a geração das credenciais de produção (Secret Key) para validar a autenticidade das mensagens.

💡

Dica de Arquitetura

Você tem flexibilidade total: pode configurar um único endpoint para receber todos os eventos ou configurar endpoints diferentes para cada tipo de evento. Basta garantir que sua aplicação saiba interpretar os payloads corretamente.

3. Regras de Processamento e Boas Práticas

Para garantir a estabilidade da integração, é fundamental que sua aplicação obedeça aos critérios de resposta e tempo limite definidos abaixo.

3.1. Código de Resposta Esperado

Sempre que sua aplicação receber um evento, ela deve retornar um status HTTP 200 OK para confirmar o sucesso da entrega.

• Qualquer código de resposta fora da faixa 2xx (como 400, 404 ou 500) será interpretado pelo nosso sistema como uma falha no recebimento.

3.2. Limites de Tempo (timeout)

O Webhook possui um timeout rígido de 5 segundos.

• Se sua aplicação não responder dentro deste prazo, a conexão será encerrada e o envio será marcado como falha.

📘

Dica de Performance (Processamento Assíncrono)

Evite realizar operações demoradas (como salvar no banco de dados ou chamar APIs externas) enquanto o webhook espera sua resposta.

A melhor prática é: Receba o evento, retorne 200 OK imediatamente e processe a lógica de negócio em segundo plano (background job/fila).

4. Política de Retentativa e Resiliência

O que acontece se a entrega falhar? Caso sua aplicação esteja indisponível ou responda com erro, nosso sistema realizará até 5 tentativas automáticas em um intervalo total de 40 minutos.

Tabela de Tentativas (Backoff)

📘

Idempotência: devido a intermitências de rede, é possível que você receba o mesmo evento mais de uma vez. Prepare sua aplicação para lidar com eventos duplicados de forma segura.

5. Suporte

Dúvidas técnicas sobre a integração? Envie um e-mail para: [email protected].