Visão geral dos webhooks

Entenda como a PagPolar avisa o seu servidor quando uma venda ou assinatura muda e por que o webhook também recebe as vendas do checkout.

O que é e por que usar

Webhook é uma requisição POST que a PagPolar envia para uma URL do seu servidor quando algo acontece: uma venda foi paga, um boleto venceu, uma assinatura foi cancelada.

Sem webhook, o seu sistema teria que perguntar à API, sem parar, se algo mudou. Com webhook, a PagPolar avisa na hora.

O webhook da sua credencial

Cada credencial da API nasce com um webhook próprio, com a URL, os eventos e o token escolhidos na criação. Veja O webhook da credencial.

O webhook da chave de Homologação

Ao criar a chave de Homologação, a PagPolar copia o webhook dela para o ambiente de testes, com a mesma URL, os mesmos eventos e o mesmo token. Os avisos das vendas e assinaturas de teste chegam nessa URL, no mesmo formato dos avisos reais.

Leve em conta duas regras:

A cópia não acompanha as edições. Mudar a URL, os eventos ou o token em Configurações → Webhooks não muda o webhook do ambiente de testes. Os avisos de teste continuam indo para a URL, os eventos e o token escolhidos na criação da chave. Para trocar, revogue a chave de Homologação e crie outra.
Na sua conta real, o webhook continua existindo e recebe os avisos reais. A mesma URL pode receber avisos reais e avisos de teste.

Para reconhecer um aviso de teste de uma venda criada pela API, compare data.source.api_credential_id com o credential_id que GET /me devolve para a chave de Homologação.

Ele recebe também as vendas do checkout

O webhook da credencial recebe os eventos de todas as vendas e assinaturas da conta, não só as que a sua integração criou. Para separar, use o campo source. Veja Canal da venda.