Webhook é o caminho inverso da API: em vez de você perguntar se houve venda, nós avisamos assim que acontece.

Configurando

Em Configurações → Webhooks, informe a URL do seu endpoint e marque os eventos que quer receber. A URL precisa ser HTTPS e responder em até 10 segundos.

Eventos

• sale.created — venda criada, ainda sem pagamento confirmado
• sale.approved — pagamento aprovado. É o que a maioria usa
• sale.refunded — valor devolvido
• product.created — produto criado
• dispute.opened — disputa aberta

Sempre valide a assinatura

Cada envio traz o cabeçalho X-PagOnline-Signature, um HMAC SHA-256 do corpo da requisição com o segredo do seu webhook. Sem validar, qualquer um que descubra sua URL pode forjar uma venda aprovada.

Use comparação de tempo constante — hash_equals em PHP — em vez de ==.

Responda rápido

Devolva 200 assim que receber e processe depois, em fila. Processamento pesado dentro do webhook estoura o tempo limite e gera reenvio.

Reenvios e duplicidade

Se sua URL não responder 200, tentamos de novo com intervalos crescentes, até 5 vezes. Por isso o mesmo evento pode chegar duas vezes.

Guarde o id do evento e ignore o que já foi processado. Sem isso, uma instabilidade de rede vira pedido duplicado ou e-mail enviado duas vezes.

Testando

Use um serviço de URL temporária para inspecionar o payload antes de escrever o código. O painel guarda o histórico de entregas com status e resposta.