Webhooks

Webhooks são como a Gravity Play avisa o seu sistema quando algo acontece — um pagamento confirmado, uma assinatura renovada, um estorno. Eles são a fonte da verdade: chegam mesmo que o cliente feche o navegador.

Duas formas de receber

Endpoints do painel

Cadastre URLs fixas em Integrações → Webhooks e escolha os eventos (e, se quiser, os produtos). Recebem todos os eventos que casarem.

postbackUrl da cobrança

Ao criar uma cobrança via API, informe um postbackUrl. Ele recebe os eventos daquela transação específica — somado aos endpoints do painel.

Eventos

Evento	Quando dispara
`payment.pending`	Uma cobrança foi criada e aguarda pagamento (PIX/boleto gerado).
`payment.paid`	Um pagamento foi confirmado.
`payment.completed`	Compra concluída — a janela de estorno expirou e segue paga.
`payment.failed`	Um pagamento foi recusado.
`payment.refunded`	Um pagamento foi estornado.
`payment.chargeback`	Um pagamento sofreu chargeback.
`subscription.created`	Uma assinatura ficou ativa.
`subscription.renewed`	Uma assinatura foi renovada (novo ciclo pago).
`subscription.canceled`	Uma assinatura foi cancelada.
`subscription.payment_failed`	A cobrança de uma assinatura falhou (dunning).

Formato do payload

Toda entrega é um POST com corpo JSON neste formato:

{
  "id": "whd_9f2c...",
  "event": "payment.paid",
  "createdAt": "2026-06-10T01:19:06.544Z",
  "data": {
    "id": "pay_...",
    "provider": "STRIPE",
    "status": "PAID",
    "amountInCents": 12900,
    "currency": "usd",
    "productId": "prod_...",
    "offerId": "off_...",
    "subscriptionId": "sub_...",
    "chargeId": "chg_2e59538f...",
    "customerEmail": "client@acme.com",
    "customer": {
      "name": "Maria Silva",
      "email": "client@acme.com",
      "document": "12345678909",
      "phone": "11987654321",
      "address": {
        "zipCode": "01310100",
        "street": "Avenida Paulista",
        "number": "1000",
        "complement": "Conj 101",
        "neighborhood": "Bela Vista",
        "city": "São Paulo",
        "state": "SP"
      }
    },
    "metadata": { "invoiceId": "1234" },
    "createdAt": "2026-06-10T01:19:06.544Z",
    "offer": {
      "id": "off_...",
      "name": "Plano Pro",
      "description": "Acesso completo",
      "billingType": "RECURRING",
      "billingCycle": "MONTHLY",
      "priceInCents": 12900,
      "currency": "usd",
      "setupFeeInCents": null,
      "trialDays": null,
      "maxCharges": null,
      "statementDescriptor": "ACME PRO",
      "product": { "id": "prod_...", "name": "Acme SaaS" }
    }
  }
}

Campos do data nos eventos payment.*:

Campo	Descrição
`id`	Id do pagamento na Gravity Play.
`provider`	Gateway que processou (`STRIPE`, `ASAAS`, `EFI`, `PAGARME`).
`status`	`PENDING`, `PAID`, `FAILED`, `REFUNDED`, `EXPIRED` (PIX vencido).
`amountInCents`	Valor em centavos.
`currency`	Moeda (ex.: `brl`, `usd`).
`productId`	Produto associado (pode ser `null` em cobranças avulsas).
`offerId`	Oferta associada (`null` em cobranças avulsas via API).
`subscriptionId`	Assinatura, quando o pagamento é de um ciclo (`null` caso contrário).
`chargeId`	Id da cobrança avulsa (`/v1/charges`) que originou o evento, se houver.
`customerEmail`	E-mail do comprador. Legado — prefira `customer.email`.
`customer`	Objeto completo do comprador (veja abaixo).
`metadata`	A metadata que você enviou na criação da cobrança/oferta.
`createdAt`	Quando o pagamento foi criado.
`offer`	Objeto da oferta (veja abaixo). Presente sempre que houver `offerId`.

O objeto `customer`

Todos os eventos payment.* e subscription.* trazem o objeto customer com os dados que o comprador preencheu no checkout. Campos não coletados naquele fluxo vêm como null.

Campo	Descrição
`name`	Nome completo do comprador.
`email`	E-mail do comprador.
`document`	CPF/CNPJ, só dígitos (checkouts BR — `null` em pagamentos via Stripe).
`phone`	Telefone com DDD, só dígitos (quando o método coleta — `null` caso contrário).
`address`	Endereço de cobrança (quando o método coleta) ou `null`.

O address, quando presente, tem o formato:

Campo	Descrição
`zipCode`	CEP, só dígitos.
`street`	Rua/logradouro.
`number`	Número.
`complement`	Complemento (`null` se não informado).
`neighborhood`	Bairro.
`city`	Cidade.
`state`	UF (2 letras).

Quando cada campo existe. O endereço é coletado no cartão (Asaas/Pagar.me) e no boleto — em pagamentos PIX o checkout pede só os dados pessoais, então customer.address vem null. O telefone é coletado no cartão (gateways BR) e no PIX Pagar.me. Pagamentos anteriores a esta versão não têm os campos novos preenchidos (null).

Para eventos de uma cobrança via API, o data.metadata traz a metadata que você enviou na criação — use o invoiceId (ou o que for) para dar baixa.

O objeto `offer`

Todo evento cujo data tenha um offerId — pagamentos de checkout de oferta e todos os eventos subscription.* — vem com o objeto offer completo embutido, para você reagir aos dados comerciais (nome, preço, ciclo) sem uma chamada extra à API.

Campo	Descrição
`id`	Id da oferta.
`name`	Nome da oferta.
`description`	Descrição da oferta (`null` se não houver).
`billingType`	`ONE_TIME` ou `RECURRING`.
`billingCycle`	`WEEKLY`, `MONTHLY`, `YEARLY`… (`null` em `ONE_TIME`).
`priceInCents`	Preço da oferta em centavos.
`currency`	Moeda da oferta.
`setupFeeInCents`	Taxa de adesão (1º ciclo), se houver (`null`).
`trialDays`	Dias de teste antes da 1ª cobrança, se houver (`null`).
`maxCharges`	Nº máximo de cobranças da recorrência, se houver (`null`).
`statementDescriptor`	Texto que aparece na fatura do cartão (`null` se não definido).
`product`	`{ id, name }` do produto da oferta.

Cobranças avulsas não têm oferta. Eventos de cobranças criadas via POST /v1/charges (sem uma oferta) não trazem o objeto offer — nesses casos offerId é null. Use o data.metadata e o chargeId para reconciliar.

Os eventos subscription.* usam um data menor (id, status, offerId, customerEmail, customer, currentPeriodEnd) — também com os objetos customer e offer embutidos:

{
  "id": "whd_...",
  "event": "subscription.renewed",
  "createdAt": "2026-06-10T01:19:06.544Z",
  "data": {
    "id": "sub_...",
    "status": "active",
    "offerId": "off_...",
    "customerEmail": "client@acme.com",
    "customer": {
      "name": "Maria Silva",
      "email": "client@acme.com",
      "document": "12345678909",
      "phone": "11987654321",
      "address": null
    },
    "currentPeriodEnd": "2026-07-10T01:19:06.544Z",
    "offer": {
      "id": "off_...",
      "name": "Plano Pro",
      "billingType": "RECURRING",
      "billingCycle": "MONTHLY",
      "priceInCents": 12900,
      "currency": "usd",
      "product": { "id": "prod_...", "name": "Acme SaaS" }
    }
  }
}

E os headers:

Header	Descrição
`X-GravityPay-Event`	O tipo do evento (ex.: `payment.paid`).
`X-GravityPay-Delivery`	Id único da entrega (= `id` do payload). Idempotência.
`X-GravityPay-Signature`	Assinatura HMAC (veja abaixo).

Validando a assinatura

Cada entrega é assinada com HMAC-SHA256. O header tem o formato t=<unix>,v1=<hmac>, e o HMAC é calculado sobre `${t}.${body}` usando o secret.

Qual secret usar? - Endpoints do painel: o signing secret exibido ao criar o endpoint. - postbackUrl: o postbackSecret retornado na resposta do POST /v1/charges daquela cobrança. Cada cobrança tem o seu.

import crypto from "node:crypto";

function verify(secret, header, rawBody) {
  const [t, v1] = header.split(",").map((p) => p.split("=")[1]);
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${t}.${rawBody}`)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}

// Express — use o corpo CRU (raw), não o JSON já parseado.
app.post("/webhooks/gravitypay", express.raw({ type: "*/*" }), (req, res) => {
  const ok = verify(
    process.env.POSTBACK_SECRET,
    req.headers["x-gravitypay-signature"],
    req.body.toString("utf8"),
  );
  if (!ok) return res.status(400).end();

  const event = JSON.parse(req.body.toString("utf8"));
  if (event.event === "payment.paid") {
    // dê baixa na fatura event.data.metadata.invoiceId
  }
  res.status(200).end();
});

import hmac, hashlib

def verify(secret: str, header: str, raw_body: str) -> bool:
    parts = dict(p.split("=") for p in header.split(","))
    expected = hmac.new(
        secret.encode(), f"{parts['t']}.{raw_body}".encode(), hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(parts["v1"], expected)

Use o corpo cru. Valide a assinatura sobre o corpo exatamente como recebido (raw). Se você re-serializar o JSON, a assinatura não vai bater.

postbackUrl

Quando você cria uma cobrança com postbackUrl, todos os eventos daquela transação (payment.paid, payment.failed, payment.refunded) são entregues também nessa URL — além dos endpoints do painel. É ideal para reconciliar uma fatura sem precisar manter um endpoint fixo. O postbackSecret que valida essas entregas vem uma única vez, na resposta da criação da cobrança. Guarde-o junto com o id da cobrança/fatura.

Idempotência

A mesma entrega pode chegar mais de uma vez (ex.: ao reprocessar). Use o X-GravityPay-Delivery (= id do payload) como chave de idempotência e ignore duplicatas.

Resposta e re-tentativas

Responda 2xx rapidamente (idealmente em até alguns segundos) para confirmar o recebimento. Qualquer outro status é tratado como falha. Entregas que falham ficam registradas no painel (Integrações → Webhooks → Entregas), de onde você pode reprocessar manualmente.

Introdução

Guias

Duas formas de receber

Endpoints do painel

postbackUrl da cobrança

Eventos

Formato do payload

O objeto `customer`

O objeto `offer`

Validando a assinatura

postbackUrl

Idempotência

Resposta e re-tentativas

​Duas formas de receber

Endpoints do painel

postbackUrl da cobrança

​Eventos

​Formato do payload

​O objeto customer

​O objeto offer

​Validando a assinatura

​postbackUrl

​Idempotência

​Resposta e re-tentativas

Duas formas de receber

Eventos

Formato do payload

O objeto `customer`

O objeto `offer`

Validando a assinatura

postbackUrl

Idempotência

Resposta e re-tentativas