# Configurar o webhook

URL: https://staging.pagpolar.com/docs/webhooks/configurar

> 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](/docs/webhooks/autenticar-requisicoes#token-do-webhook). O passo a passo da criação está em [Credenciais da API](/docs/guias/fundamentos/credenciais).

## 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](/docs/webhooks/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:

1. Abra **Configurações → Webhooks**.
2. Encontre o webhook com o nome `API Integration — ` seguido do nome da sua integração.
3. Abra **Editar webhook** e altere **URL**, **Tipos de evento**, **Máximo de tentativas** ou **Authorization (Bearer token)**.
4. Salve.

Na chave de Homologação, a edição não chega ao ambiente de testes. Veja [O webhook da chave de Homologação](/docs/webhooks#homologacao).

Antes de trocar o valor de **Authorization (Bearer token)**, leia [O token do webhook](/docs/webhooks/autenticar-requisicoes#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:

```text
Este webhook está vinculado a uma credencial de API ativa e não pode ser desativado. Revogue a credencial primeiro.
```

Ao remover:

```text
Este webhook está vinculado a uma credencial de API ativa e não pode ser removido. Revogue a credencial primeiro.
```

Ao [revogar a credencial](/docs/guias/fundamentos/credenciais#revogar), 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](/docs/webhooks/autenticar-requisicoes#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 `404` estão em [Entregas e retentativas](/docs/webhooks/entregas-e-retentativas#sucesso).

## Próximos passos

- [Autenticar as requisições recebidas](/docs/webhooks/autenticar-requisicoes) — Valide o header Authorization.
- [Formato do evento](/docs/webhooks/formato-do-evento) — Leia os campos que chegam.