Configurar o webhook
Cadastre a URL, escolha os eventos e saiba o que pode ou não mudar no webhook da credencial.
O webhook da credencial
Ao criar uma credencial da API, a PagPolar cria um webhook junto. A URL é informada em Configurações → API → Nova chave, no campo URL do webhook, que aceita qualquer URL válida. O webhook vale para todos os produtos da conta e aparece em Configurações → Webhooks com o nome API Integration — seguido do nome da sua integração.
Você não precisa cadastrar outro webhook em Configurações → Webhooks para receber os avisos dessa integração. Se cadastrar outro para a mesma URL, cada aviso chega duas vezes.
O token que o webhook envia é gerado junto com a credencial. Veja O token do webhook. O passo a passo da criação está em Credenciais da API.
Escolher os eventos
No mesmo formulário, o campo Eventos define quais avisos o webhook recebe:
- Em branco: recebe os 15 eventos.
- Com eventos marcados: recebe só os marcados.
Veja o que cada evento significa no Catálogo de eventos.
Na dúvida, receba todos
Receber um evento que você não usa não causa problema: responda 200 e ignore. Deixar de receber um evento importante faz o seu sistema perder uma mudança de status.
Mudar a URL ou os eventos depois
O formulário de edição da credencial não mostra o webhook. Para mudar a URL, os eventos ou o token:
- Abra Configurações → Webhooks.
- Encontre o webhook com o nome
API Integration —seguido do nome da sua integração. - Abra Editar webhook e altere URL, Tipos de evento, Máximo de tentativas ou Authorization (Bearer token).
- Salve.
Na chave de Homologação, a edição não chega ao ambiente de testes. Veja O webhook da chave de Homologação.
Antes de trocar o valor de Authorization (Bearer token), leia O token do webhook.
O que não dá para fazer
Enquanto a credencial estiver ativa, o webhook dela não pode ser desativado nem removido. A tentativa é recusada com status 409 e um destes avisos.
Ao desativar:
Este webhook está vinculado a uma credencial de API ativa e não pode ser desativado. Revogue a credencial primeiro.Ao remover:
Este webhook está vinculado a uma credencial de API ativa e não pode ser removido. Revogue a credencial primeiro.Ao revogar a credencial, o webhook é desativado junto.
Webhooks adicionais
Você pode criar outros webhooks, sem ligação com uma credencial, em Configurações → Webhooks → Novo Webhook. Eles recebem os mesmos eventos, com estes campos:
| Campo | Regras |
|---|---|
| Nome | Opcional, até 255 caracteres. |
| URL | Obrigatória. Uma URL válida. |
| Máximo de tentativas | De 1 a 10. Padrão: 5. |
| Authorization (Bearer token) | Opcional. Veja O token do webhook. |
| Tipos de evento | Os eventos que o webhook recebe. |
| Produtos | Todos os produtos ou só os escolhidos. |
Um webhook restrito a produtos só recebe os eventos de vendas e assinaturas desses produtos.
Requisitos da sua URL
- Pública. A PagPolar precisa alcançar a URL pela internet.
- HTTPS. Use HTTPS para proteger o token e os dados pessoais do cliente, que chegam no corpo do aviso.
- Rápida e estável. O prazo de resposta, os status aceitos e o efeito de um
404estão em Entregas e retentativas.