Os Webhooks da Bloquo são um mecanismo essencial de notificação em tempo real que garante que os clientes sejam informados imediatamente sobre qualquer alteração no status de seus pedidos de Depósito ou Retirada (Withdrawal).
Ao contrário de um sistema de polling (onde você precisa perguntar constantemente), a Bloquo envia ativamente uma solicitação HTTP POST para uma URL que você especifica no momento da criação do pedido, garantindo comunicação instantânea e eficiente.
Criação do Pedido: Ao criar um novo pedido de Depósito ou Retirada via API, o cliente deve incluir a URL de destino na propriedade WebhookUrl do corpo da solicitação.
Monitoramento: A Bloquo monitora o status interno do pedido.
Notificação: Sempre que o status do pedido muda (por exemplo, de PENDING para COMPLETED ou FAILED), a Bloquo envia uma solicitação HTTP POST para a WebhookUrl fornecida.
Confirmação: O endpoint do cliente DEVE responder com um status HTTP 200 OK para confirmar que a notificação foi recebida e será processada.
A solicitação POST enviada pela Bloquo conterá um corpo JSON detalhado com todas as informações do pedido atualizadas, incluindo:
| Campo Principal | Tipo | Descrição |
| Status | STRING | O novo status do pedido (ex: COMPLETED, FAILED). Este é o campo chave. |
| OrderId | INTEGER | O ID único do pedido Bloquo. |
| OrderType | STRING | Tipo de pedido (Withdrawal ou Deposit). |
| E2EId | STRING | Identificador End-to-End (se aplicável), útil para rastreamento. |
| RequestedAmount | DECIMAL | Valor solicitado originalmente. |
| TotalAmount | DECIMAL | Valor total após taxas. |
| FeeAmount | DECIMAL | Valor da taxa cobrada (se houver). |
| FinalizedAt | DATETIME | Carimbo de data/hora de quando o status atual foi finalizado. |
| FailureReason | STRING | O código e a descrição do motivo da falha (se o Status for FAILED). |
(Consulte os exemplos de corpo de Withdrawal Order e Deposit Order para a estrutura completa.)
Importante: As solicitações de Webhook NÃO utilizam Bearer Token, hash ou assinatura de segurança na requisição.
A segurança da comunicação é garantida pelo controle de origem (Source Validation).
Todas as requisições de webhook vêm EXCLUSIVAMENTE dos servidores de API da Bloquo.
Os servidores são segregados por ambiente (Sandbox, Produção, etc.).
Ação Requerida: Para validar a fonte da requisição em seu endpoint, você DEVE solicitar à Bloquo o endpoint de origem oficial ou o endereço IP correspondente ao seu ambiente de integração e configurar seu firewall/servidor para aceitar requisições apenas dessa origem.
A Bloquo utiliza uma robusta política de retentativas para garantir a entrega da notificação, caso seu servidor não confirme o recebimento.
| Condição de Retentativa | Ação |
| Ocorrência: | Seu servidor NÃO retornar um status HTTP 2xx (ex: 200 OK) para a Bloquo. |
| Mecanismo: | Exponential Backoff with Jitter (Atraso exponencial com variação aleatória). |
| Atraso Base: | 1 minuto. |
| Padrão: | O atraso dobra a cada tentativa, com pequena variação aleatória (aprox. 1m → 2m → 4m → 8m...). |
| Máximo: | 10 tentativas. |
| Resultado Final: | Após 10 falhas, o webhook é permanentemente marcado como Failed (Falhado) e não haverá mais tentativas automáticas. |
Para garantir uma integração de webhook confiável e eficiente, siga estas recomendações:
Resposta Imediata (200 OK): Seu endpoint deve retornar HTTP 200 OK o mais rápido possível. O processamento de lógica pesada, atualização de banco de dados ou outras tarefas demoradas DEVE ser feito de forma assíncrona (em fila/background). Isso evita timeouts e retentativas desnecessárias da Bloquo.
Idempotência: Torne seu endpoint idempotente. Se a Bloquo enviar uma notificação duplicada (o que pode ocorrer em falhas de rede antes do recebimento do 200 OK), o processamento da segunda notificação não deve causar efeitos colaterais indesejados (ex: creditar o cliente duas vezes). Utilize o OrderId e o Status para verificar se o evento já foi processado.
Registro (Logging): Registre (faça o log) todas as solicitações de webhook recebidas na íntegra. Isso é crucial para auditoria, diagnóstico de problemas e validação contra o sistema Bloquo.
Validação de Dados: Antes de processar a notificação, valide se os valores de OrderId e E2EId correspondem aos dados esperados em seu sistema.
Em caso de dúvidas, consulte nossa Documentação de API Completa ou entre em contato com o suporte.