Autenticar as requisições recebidas

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:

Authorization: Bearer <TOKEN_DO_WEBHOOK>

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 sem token envia os avisos sem o header Authorization.

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 -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": {}
  }'

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);

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.

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, 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} usando data.transaction.id.

Se o token vazar

Você tem duas saídas:

Próximos passos