Quando um cliente paga, alguém precisa avisar o seu sistema: dar baixa no pedido, separar o estoque, emitir a nota e enviar a confirmação. Fazer isso conferindo o extrato funciona no começo, mas trava a operação quando as vendas crescem. É para isso que existem os webhooks de pagamento.
O que é um webhook de pagamento
É uma notificação automática que a plataforma de pagamentos envia para um endereço (URL) do seu sistema sempre que algo acontece com uma cobrança: um Pix foi pago, um boleto foi compensado, uma compra no cartão foi aprovada ou reembolsada. Em vez de o seu sistema perguntar de tempos em tempos se o cliente já pagou, ele é avisado assim que o status muda.
Como funciona, passo a passo
- Você informa a URL: o endereço do seu sistema que vai receber os avisos, configurado no painel ou enviado no campo postbackUrl da cobrança criada pela API.
- O cliente paga: por Pix, cartão de crédito ou boleto.
- A plataforma envia o aviso: uma requisição HTTP POST com os dados do evento em JSON.
- Seu sistema confirma o pedido: confere o aviso, atualiza o status e responde com HTTP 200 para indicar que recebeu.
O que vem dentro de um webhook
Cada aviso traz um identificador único do evento, o status do pagamento e os dados da transação. Um exemplo simplificado: {"id": "evt_...", "status": "LIQUIDATED", "data": {"value": "16.5", "txId": "...", "method": "pix"}}.
Na Sila Pay, você também escolhe no painel quais eventos quer receber, como compra aprovada (purchase_approved), Pix pago (pix_paid), boleto pago (boleto_paid), Pix expirado e compra reembolsada.
Onde os webhooks ajudam no dia a dia
- Baixa automática de pedidos: o pedido passa para "pago" no seu sistema ou ERP sem ninguém conferir extrato.
- Estoque e expedição: a separação começa assim que o pagamento é confirmado.
- Produtos digitais e serviços: libere acesso, ingresso ou agendamento logo após o pagamento.
- Cobranças expiradas: saiba quando um Pix ou boleto venceu sem pagamento e retome o contato.
Quer automatizar a confirmação dos seus pedidos? Crie sua conta na Sila Pay
Boas práticas para receber webhooks
- Valide a assinatura: cada aviso da Sila Pay traz o header X-Silapay-Signature, um HMAC-SHA256 calculado com o seu secret. Confira antes de processar.
- Responda rápido: devolva HTTP 200 em até 5 segundos e deixe tarefas demoradas, como emitir a nota, para depois.
- Trate repetições: se o seu sistema não responder, a plataforma tenta de novo; use o id do evento para não processar o mesmo aviso duas vezes.
- Use HTTPS e proteja o secret: guarde-o no servidor, nunca no site ou no app.
Perguntas frequentes
Preciso ser programador para usar webhooks?
Alguém precisa preparar o endereço que recebe os avisos. Muitos ERPs e plataformas de loja já trazem esse recurso; se você usa WooCommerce ou Shopify, a Sila Pay tem plugins para integrar a sua loja.
Qual a diferença entre webhook e API?
Na API, o seu sistema chama a plataforma, por exemplo para criar uma cobrança. No webhook, é a plataforma que chama o seu sistema para avisar que algo mudou. Os dois costumam trabalhar juntos.
E se o meu sistema estiver fora do ar?
A Sila Pay faz novas tentativas automáticas quando não recebe a resposta HTTP 200. Ainda assim, vale manter uma rotina de conferência para indisponibilidades mais longas.
Onde encontro a documentação?
Em doc.silapay.pro, com a lista de eventos, o formato do payload e um exemplo de verificação da assinatura.
Confirme pedidos automaticamente, sem conferir extrato. Cadastre-se na Sila Pay