Configurando Notificações Assíncronas (Webhooks)

Webhooks são a ferramenta principal para permitir que seu sistema reaja eventos de conciliação de pagamentos do nosso Gateway, sem que seja necessário o disparo contínuo (Long Polling) de sua parte para verificar se houveram pagamentos dos PIX ou estornos de Saques.

Cadastrando Uma URL Receptora

A cada URL mapeada na nossa API POST /config/webhooks/, um Hash Secreto de Assinatura (HMAC secret) será devolvido na Response para posterior autenticação. Seu servidor deve estar hábil a responder retornos da nossa API com um HTTP Code 200 imediatamente após seu recebimento, em um limite estourado de resposta de 1000 milisegundos.

---

Isolando a regra de negócio do Receiver (Dica Valiosa)

Como a requisição bate no seu backend e espera um retorno positivo em menos de um segundo, recomendamos que o código da rota não efetue nenhum banco de dados ou lógica síncrona: grave os dados do payload numa Fila Interna sua (RabbitMQ, SQS, Redis) e passe o OK 200. Deixe seu worker interno processar os payloads com calma e lidar com concorrência para que não percamos conectividade com o seu webhook por Timeout.