Visão geral
Como a BlendFi te avisa que algo aconteceu. Modelo mental, eventos disponíveis, decisão webhook vs polling, padrão de produção.
Webhooks são como a BlendFi te avisa que algo aconteceu: um Pix chegou, um KYC foi aprovado, um depósito de USDT confirmou on-chain. São mais baratos, mais rápidos e mais confiáveis que polling.
Quando a BlendFi faz POST para você
Toda mudança de estado na superfície visível ao parceiro dispara exatamente um evento de webhook. Os tipos de evento se agrupam em:
- Ciclo de vida da conversão (7 eventos):
conversion.created,conversion.standby,conversion.completed,conversion.failed,conversion.expired,conversion.canceled,conversion.abandoned. - Transação (etapa de liquidação) (3 eventos):
transaction.sending_pix,transaction.completed,transaction.failed. Opcional, visibilidade mais granular da liquidação. - KYC do cliente final (4 eventos):
user.kyc_pending,user.kyc_approved,user.kyc_rejected,user.kyc_expired.
A lista completa com exemplos de payload está no catálogo de eventos.
Webhooks vs polling
Polling é OK para reconciliação ocasional (GET /v1/conversions/:id é seguro contra rate limit dentro de limites razoáveis). Webhooks são a escolha certa quando:
- Você precisa reagir em segundos, não em minutos (ex.: mostrar ao cliente final "pagamento recebido" no momento em que o Pix liquida).
- Você está lidando com mais que um punhado de conversões por dia (custo do polling cresce linearmente).
- Você tem um endpoint HTTPS sob seu controle.
Você não precisa escolher. A maioria das integrações em produção assina webhooks para reações rápidas e usa polling apenas como rede de segurança de reconciliação (cron diário que busca "qualquer conversão ainda em andamento" e valida contra o estado local).
O padrão de produção
Checklist para uma integração de parceiro pronta para produção:
- Endpoint HTTPS registrado via
POST /v1/webhook_endpoints. Veja Gerenciamento de endpoints. - Verificação de assinatura em toda entrega: HMAC-SHA256 sobre
{t}.{raw_body}, comparação em tempo constante, janela de replay de 300 segundos. Veja Verificação de assinatura. - Processamento idempotente: descarte duplicatas pelo
X-Blendfi-Event-Id. - Resposta rápida: retorne 2xx em menos de 500 ms; faça o trabalho real de forma assíncrona.
- Plano concreto de retentativas: aceite retentativas graciosamente; um 5xx do seu endpoint dispara nova tentativa em cerca de 30 segundos. Veja Retentativas e replay.
- Escopo de assinatura: assine apenas os eventos que você processa. Eventos novos são adicionados de forma aditiva; assinar todos não quebra quando novos chegam, mas minimiza ruído.
- Procedimento de rotação de segredo: rotacione via
POST /v1/webhook_endpoints/{id}/rotate_secretantes de qualquer susto de comprometimento. Veja Gerenciamento de endpoints. - Acesso ao histórico de entregas:
GET /v1/webhook_endpoints/{id}/deliveries. Útil para diagnóstico: "a BlendFi tentou nos alcançar nesse horário?" - Reentrega manual:
POST /v1/webhook_deliveries/{id}/redeliverpara reprocessar um evento específico depois de uma correção. - Fluxo de teste local: acione endpoints
test_helpersno sandbox para exercitar o ciclo de vida sem esperar pagamentos reais. Veja Testes no sandbox.
Não pule a verificação de assinatura
Um receptor de webhook não autenticado expõe uma superfície de execução remota de código (RCE) pela rede pública. Verifique assinaturas em todo request, falhe fechado e logue falhas de assinatura para detectar tentativas de ataque cedo.
Páginas desta seção
Gerenciamento de endpoints
Criar, listar, atualizar e apagar endpoints. Rotacionar segredo sem downtime.
Verificação de assinatura
HMAC-SHA256, headers, código funcional em curl, Node e Python.
Catálogo de eventos
Cada tipo com exemplos de payload, quando dispara, o que fazer.
Retentativas e replay
Cronograma, semântica de status, fila de mensagens com falha (DLQ), reentrega manual.
Testes no sandbox
Acione entregas via test_helpers, debug de divergências de assinatura.