# Visão geral dos webhooks

URL: https://staging.pagpolar.com/docs/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](/docs/webhooks/configurar#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](/docs/guias/fundamentos/ambientes#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`](/docs/webhooks/formato-do-evento#source) com o `credential_id` que [`GET /me`](/docs/referencia/autenticacao/get-current-credential) 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](/docs/webhooks/formato-do-evento#source).

## Como um evento chega até você

O diagrama mostra o caminho de um evento, da mudança na PagPolar até o seu servidor.

```mermaid
sequenceDiagram
  autonumber
  participant P as PagPolar
  participant F as Fila de entrega
  participant W as Seu servidor de webhook
  P->>F: venda ou assinatura mudou, um envio por webhook
  F->>W: POST com Authorization Bearer
  alt resposta 2xx em até 10 segundos
    W-->>F: entrega concluída
  else 404, 410, domínio inexistente ou certificado inválido
    W-->>F: falha, webhook desativado
  else outro erro ou 10 segundos sem resposta
    W-->>F: falha
    F->>W: nova tentativa cerca de 30 segundos depois, até esgotar e desativar
  end
```

Quantas tentativas são feitas e o que conta como entrega está em [Entregas e retentativas](/docs/webhooks/entregas-e-retentativas).

## Próximos passos

- [Playground](/docs/webhooks/playground) — Monte um evento, edite o JSON e envie um teste para o seu webhook.
- [Autenticar as requisições recebidas](/docs/webhooks/autenticar-requisicoes) — Confirme que o aviso veio da PagPolar.
- [Formato do evento](/docs/webhooks/formato-do-evento) — Leia o envelope e os campos de cada bloco.
- [Processar eventos sem duplicar](/docs/webhooks/processar-sem-duplicar) — Trate repetições e eventos fora de ordem.
- [Catálogo de eventos](/docs/webhooks/eventos) — Os 15 eventos e quando cada um é enviado.