Receber webhook

Como receber notificações de mudança de status no seu servidor.

Vanilla Pag envia um POST JSON ao webhook configurado no projeto sempre que uma transação muda de status. O corpo é assinado com HMAC-SHA256 usando o `webhook_secret` da credencial — verifique o header `X-Signature` antes de processar o evento. Em caso de falha (resposta não-2xx ou timeout > 10s), tentamos de novo com backoff: 30s, 2min, 8min, 30min, 2h.

Endpoint

POST (seu endpoint)

Headers

Header	Valor
Content-Type	application/json
User-Agent	VanillaPag-Webhooks/1.0
X-Event	PAID
X-Transaction-Id	tx_2sQfgT…
X-Signature	sha256=<hmac-hex>

Request body

Field	Type	Description
id	string	ID da transação.
status	string	Novo status: PAID, REFUNDED, EXPIRED, CANCELLED, REFUSED.
amount	integer	Valor em centavos.
payment_method	string	Sempre `pix` nesta versão.
customer.name	string	Nome do cliente final.
customer.email	string	E-mail do cliente final.
customer.phone	string	Telefone do cliente, se informado no create.
customer.document	string	CPF ou CNPJ do cliente.
pix.qr_code	string	Payload PIX copia-e-cola usado na cobrança.
pix.end2end_id	string	Identificador end-to-end do PIX (nulo enquanto não confirmado).
paid_at	string	ISO 8601. Preenchido quando `status = PAID`.
created_at	string	ISO 8601. Quando a cobrança foi criada.
updated_at	string	ISO 8601. Última mudança de status.
metadata	object	Objeto reservado para uso futuro.

Example

Request

{
  "id": "tx_2sQfgT...",
  "status": "PAID",
  "amount": 1990,
  "payment_method": "pix",
  "customer": {
    "name": "Cliente Exemplo",
    "email": "[email protected]",
    "phone": "",
    "document": "12345678901"
  },
  "pix": {
    "qr_code": "00020126410014BR.GOV.BCB.PIX...",
    "end2end_id": null
  },
  "paid_at": "2026-05-27T17:24:11Z",
  "metadata": {},
  "created_at": "2026-05-27T17:20:02Z",
  "updated_at": "2026-05-27T17:24:11Z"
}