Webhooks

Webhooks são chamadas HTTP que a SeventyOne Pay faz para o seu servidor quando algo acontece — por exemplo, quando um PIX é pago. Assim você não precisa consultar a API a cada instante.

Como configurar

1. No painel, abra Webhooks e crie um endpoint.
2. Informe a URL (obrigatoriamente https://) e escolha os eventos que quer receber (ou * para todos).
3. Copie o segredo de assinatura (whsec_…). Ele é exibido na criação; guarde-o em variável de ambiente. Você usa esse segredo para verificar a assinatura.

URLs permitidas

Por segurança, só entregamos para endereços públicos. URLs que apontam para redes internas (localhost, IPs privados, endereços de metadados de nuvem) são bloqueadas, e redirecionamentos não são seguidos: informe a URL final.

Como é a chamada

POST com corpo JSON e estes headers:

Header	Conteúdo
content-type	application/json
user-agent	SeventyOnePay-Webhooks/1.0
x-seventyone-event	Tipo do evento, ex.: payment.approved.
x-seventyone-event-id	Identificador único do evento. Use para deduplicar.
x-seventyone-timestamp	Momento do envio (segundos desde 1970).
x-seventyone-signature	Assinatura: v1=<hex>.
x-seventyone-signature-version	v1.
x-seventyone-attempt	Número da tentativa (1, 2, 3…).

Corpo do evento

{
  "id": "3f1e9a52-0000-0000-0000-00000000000a",
  "type": "payment.approved",
  "created_at": "2026-01-01T12:05:00.000Z",
  "merchant_id": "5c4d3e2f-0000-0000-0000-000000000003",
  "data": {
    "id": "0b9f1c2e-0000-0000-0000-000000000001",
    "object": "payment",
    "pix_payment_id": "7a1d2c3e-0000-0000-0000-000000000002",
    "external_id": "1001",
    "amount": 1990,
    "currency": "BRL",
    "status": "paid",
    "merchant_id": "5c4d3e2f-0000-0000-0000-000000000003",
    "fee_amount": 100,
    "net_amount": 1890,
    "fee_percent": 5
  }
}

data.id é o payment_id devolvido na criação da cobrança, e data.external_id é o valor que você enviou. Os valores estão em centavos.

Há dois formatos de corpo, escolhidos por webhook no painel: o formato padrão (acima) e um formato de notificação (notification_v1) com client, transaction e orderItems, para apps que transformam eventos em notificações no celular. A assinatura funciona igual nos dois.

O que seu endpoint deve fazer

1. Ler o corpo bruto (os bytes exatos recebidos).
2. Verificar a assinatura e o timestamp.
3. Responder 2xx rapidamente (o prazo é de 15 segundos) e processar o trabalho pesado depois.
4. Ser idempotente: o mesmo evento pode chegar mais de uma vez. Deduplique por x-seventyone-event-id.
5. Não depender de ordem: eventos podem chegar fora de sequência.