Webhooks & API

O fluxo é simples: um fato acontece na escola → o Proa Pay enfileira o evento → um worker entrega via HTTPS POST ao seu endpoint, assinado. Você valida a assinatura, responde 2xx e processa. Se o seu endpoint cair, re-tentamos com backoff.

Nesta primeira versão a saída é somente de eventos (webhooks-out). Uma API de leitura (REST) e conectores nativos vêm a seguir.

No painel admin, em Conta → Integrações → Criar webhook: informe um nome, a URL HTTPS do seu endpoint e marque os eventos desejados. Ao salvar, enviamos um evento ping de verificação — se ele responder 2xx, o endpoint fica ativo.

Você recebe um segredo de assinatura (whsec_…) uma única vez — guarde-o com segurança; é com ele que você valida cada entrega. Pode pausar, re-verificar e ver o histórico de entregas a qualquer momento.

Toda entrega tem o mesmo envelope, com os campos específicos em data:

POST https://seu-endpoint.com/webhook
Content-Type: application/json
X-AppmaxEdu-Signature: sha256=<hmac-hex>
X-AppmaxEdu-Timestamp: 1781524667000
Idempotency-Key: 3f1c…(= id do envelope)

{
  "id": "3f1c2b6e-...",          // único por evento — use como chave de dedupe
  "event": "invoice.paid",
  "api_version": "v1",
  "occurred_at": "2026-06-15T13:00:00.000Z",
  "tenant_id": "a03bb4a7-...",   // a escola (estabelecimento)
  "data": { /* payload mínimo do evento — ver catálogo */ }
}

Campos fixos do envelope (iguais em todo evento):

• id— ID único do envelope (UUID) — repetido no header Idempotency-Key
• event— tipo do evento (ex.: 'invoice.paid')
• api_version— versão do contrato de saída (ex.: 'v1')
• occurred_at— quando o evento ocorreu (ISO 8601, UTC)
• tenant_id— ID opaco do estabelecimento que originou o evento
• data— objeto com os campos específicos do evento (detalhados por evento abaixo)

Cabeçalhos HTTP de cada entrega (POST application/json):

• content-type— sempre application/json
• X-AppmaxEdu-Signature— sha256=<HMAC-SHA256 de "{timestamp}.{corpo}" usando o segredo do endpoint>
• X-AppmaxEdu-Timestamp— momento do envio (Unix ms); entra na assinatura — rejeite se diferir mais de 5 min do agora
• Idempotency-Key— igual ao id do envelope — use para deduplicar reentregas de um mesmo evento

A assinatura é HMAC-SHA256 sobre `${timestamp}.${corpo}`, com o timestamp também no cabeçalho. Rejeite requisições fora de uma janela de 5 minutos — isso previne ataques de replay. Compare em tempo constante.

import crypto from 'node:crypto';

// Em cada request, valide assinatura + janela de 5 min ANTES de processar.
function verificar(rawBody, headers, secret) {
  const sig = headers['x-appmaxedu-signature'];
  const ts = Number(headers['x-appmaxedu-timestamp']);
  if (!Number.isFinite(ts) || Math.abs(Date.now() - ts) > 5 * 60 * 1000) {
    return false; // fora da janela → possível replay
  }
  const esperado =
    'sha256=' +
    crypto.createHmac('sha256', secret).update(`${ts}.${rawBody}`).digest('hex');
  const a = Buffer.from(esperado);
  const b = Buffer.from(sig ?? '');
  return a.length === b.length && crypto.timingSafeEqual(a, b); // tempo constante
}

Cada evento carrega no data apenas os campos abaixo — o mesmo contrato que você marca na tela de criação do webhook. Esta lista é gerada a partir do catálogo do sistema: quando um evento novo entra, ele aparece aqui automaticamente.

Enriquecimento opcional (dados do pagador). Em invoice.paid e invoice.refunded, o dono da escola pode ativar no endpoint o envio dos dados de contato do pagador (adulto) — mediante aceite de tratamento de dados (DPA). Quando ativo, data traz também:

• payer_document— CPF do pagador (adulto), só dígitos — chave de conciliação; só quando o enriquecimento está ativo no endpoint
• payer_email— e-mail do pagador (adulto) — só quando o enriquecimento está ativo no endpoint
• payer_name— nome do pagador (adulto) — só quando o enriquecimento está ativo no endpoint

Use payer_document (CPF, só dígitos) como chave estável para casar a compra com o cadastro da sua ferramenta. Esses campos nunca incluem dados do aluno/menor.

Consideramos entregue qualquer resposta 2xx em até 10s. Em falha (timeout, 4xx/5xx), re-tentamos com backoff exponencial + jitter (até 16 tentativas, ~72h). Esgotadas as tentativas, a entrega vai para não-entregue e você pode reenviar manualmente pelo painel.

As entregas são at-least-once: o mesmo evento pode chegar mais de uma vez (ex.: você respondeu 2xx mas demorou). Deduplique pelo Idempotency-Key / id do envelope. Cada (evento, endpoint) é entregue com sucesso no máximo uma vez.

Por padrão os payloads são minimizados: carregam ids, valores em centavos, status e datas. Dados de contato do pagador (adulto) — CPF, e-mail e nome — só saem quando o dono da escola ativa explicitamente o enriquecimento no endpoint, com aceite de tratamento de dados (DPA). Dados pessoais de alunos menores (nome, CPF, nascimento) nunca são enviados.

Só aceitamos endpoints HTTPS com IP público (bloqueamos redes internas — proteção SSRF), validado a cada envio. Registramos cada entrega (o que saiu, para qual endpoint, quando) para atender pedidos de titular e auditoria.