# Autenticar as requisições recebidas

URL: https://staging.pagpolar.com/docs/webhooks/autenticar-requisicoes

> Valide o header Authorization antes de processar qualquer evento de webhook.

A URL do seu webhook é pública. Qualquer pessoa pode enviar um `POST` para ela fingindo ser a PagPolar. Por isso, confira o header `Authorization` **antes** de processar o evento.

## Como a PagPolar se identifica

Todo aviso do webhook da credencial chega com este header:

```text
Authorization: Bearer <TOKEN_DO_WEBHOOK>
```

> **Não é o token de acesso da API**
>
> Este `Authorization` é o que a PagPolar envia **para** o seu servidor, com o **token do webhook**. Ele não tem relação com o token de acesso que você envia **para** a API, obtido em [`POST /auth/token`](/docs/referencia/autenticacao/create-access-token). São dois valores diferentes, em direções diferentes. Veja [Autenticação](/docs/guias/fundamentos/autenticacao).

## O token do webhook

O token é exibido uma única vez na janela **Chave criada com sucesso**, ao criar a credencial. O token criado junto com a credencial tem 32 caracteres hexadecimais. Se você trocar o token em **Configurações → Webhooks**, ele passa a ter o formato que você digitou ou gerou. O valor é o mesmo em todos os avisos daquele webhook até ser trocado.

O webhook da credencial sempre tem token. Um [webhook adicional](/docs/webhooks/configurar#webhooks-adicionais) sem token envia os avisos sem o header `Authorization`.

> **Digite só o token, sem Bearer**
>
> O valor do campo **Authorization (Bearer token)** chega no header como `Authorization: Bearer <valor do campo>`. A PagPolar acrescenta o `Bearer ` sozinha: se você digitar `Bearer abc`, o header chega como `Bearer Bearer abc`. Ao trocar o valor, atualize também o valor que o seu servidor confere.

## Validar o header

1. Guarde o token em uma variável de ambiente do servidor.
2. Monte o valor esperado: `Bearer ` seguido do token.
3. Compare com o header recebido usando uma comparação de tempo constante.
4. Se não bater, responda `401` e não processe nada.
5. Se bater, responda `200` e processe o evento.

#### cURL

Use cURL para testar o seu servidor, simulando um aviso:

    ```bash
    curl -X POST "https://seu-servidor.exemplo.com/webhooks/pagpolar" \
      -H "Authorization: Bearer <TOKEN_DO_WEBHOOK>" \
      -H "Content-Type: application/json" \
      -d '{
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "event": "TRANSACTION_PAID",
        "creation_date": "2026-09-15T14:35:05.000Z",
        "version": "1.0.0",
        "data": {}
      }'
    ```

    Com o token certo, o seu servidor deve responder `200`. Troque o token por qualquer outro valor: a resposta deve ser `401`.

#### Node.js

Exemplo com Express. Instale com `npm install express`.

    ```js
    import express from 'express';
    import { timingSafeEqual } from 'node:crypto';

    const app = express();
    app.use(express.json());

    const expectedAuthorization = Buffer.from(
      `Bearer ${process.env.PAGPOLAR_WEBHOOK_TOKEN}`,
    );

    const isFromPagPolar = (request) => {
      const receivedAuthorization = Buffer.from(request.get('authorization') ?? '');

      return (
        receivedAuthorization.length === expectedAuthorization.length &&
        timingSafeEqual(receivedAuthorization, expectedAuthorization)
      );
    };

    app.post('/webhooks/pagpolar', (request, response) => {
      if (!isFromPagPolar(request)) {
        return response.sendStatus(401);
      }

      response.sendStatus(200);

      console.log('Evento recebido:', request.body.event);
    });

    app.listen(3000);
    ```

> **Por que comparação de tempo constante**
>
> Uma comparação comum (`===`) para no primeiro caractere diferente. Medindo o tempo de resposta, um atacante consegue descobrir o token aos poucos. `timingSafeEqual` leva sempre o mesmo tempo.

Responder `401` conta como falha de entrega. Se for um aviso verdadeiro com o token desatualizado no seu servidor, a PagPolar tenta de novo. Veja [Entregas e retentativas](/docs/webhooks/entregas-e-retentativas).

## O que não existe

* **Não há assinatura do corpo (HMAC).** O token prova quem enviou, mas o corpo não é assinado.
* **Não há lista de IPs de origem** publicada para os avisos.

Por isso:

* use [HTTPS na URL do webhook](/docs/webhooks/configurar#requisitos-da-url), para o token e o corpo não trafegarem abertos;
* antes de uma ação de alto valor, como liberar um produto caro, confirme o status em [`GET /sales/{identifier}`](/docs/referencia/vendas/get-sale) usando `data.transaction.id`.

## Se o token vazar

Você tem duas saídas:

| Opção          | Como                                                                                                                                                                                            | Efeito                                                                   |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| Trocar o token | Em **Configurações → Webhooks**, edite o webhook da credencial e troque o valor do campo **Authorization (Bearer token)**, [sem `Bearer`](#token-do-webhook). Atualize o valor no seu servidor. | A PagPolar passa a enviar o novo valor. A chave de API continua a mesma. |
| Trocar tudo    | [Revogue a credencial](/docs/guias/fundamentos/credenciais#revogar) e crie outra.                                                                                                               | Chave de API e token novos. Atualize os dois no seu servidor.            |

## Próximos passos

- [Processar eventos sem duplicar](/docs/webhooks/processar-sem-duplicar) — Trate repetições e eventos fora de ordem.
- [Entregas e retentativas](/docs/webhooks/entregas-e-retentativas) — Saiba o que conta como entrega.