Webhooks assinados: confie no evento, não no polling

Webhook é uma requisição HTTP que um sistema envia para uma URL sua no instante em que um evento acontece, como um pagamento confirmado. Em vez de o seu código perguntar de minuto em minuto "já pagou?" (o chamado polling), o gateway avisa você, uma vez, com os dados do evento no corpo da requisição.

No HeroPay, os webhooks avisam o seu sistema sobre 9 eventos do ciclo de pagamento: pagamento confirmado, Pix gerado, boleto emitido, cartão recusado, estorno, chargeback e os três momentos da assinatura (ativação, atualização e cancelamento). Cada evento chega como POST JSON assinado com HMAC SHA-256 no header X-HeroPay-Signature e é reenviado automaticamente se o seu endpoint falhar. Webhooks não têm custo: estão incluídos em qualquer conta, inclusive no sandbox gratuito, e você só paga pela transação aprovada (Pix R$ 0, boleto R$ 0, cartão 3,49%, veja preços). É para quem constrói SaaS, app, curso ou loja e precisa liberar acesso, emitir nota ou avisar o time sem depender de alguém olhando o painel.

Criar conta sandbox · Ler a documentação

O que é webhook e para que serve?

Pense no webhook como uma "API ao contrário". Numa API comum, o seu sistema chama o gateway e pede uma informação. No webhook, o gateway chama o seu sistema e entrega a informação sem ser perguntado. Por isso o nome vem de hook, gancho: você pendura uma URL num evento e, quando ele acontece, a requisição cai nela.

Em pagamentos, isso resolve um problema concreto: o dinheiro não confirma no momento em que o comprador clica em "pagar". O Pix confirma quando o banco do comprador liquida, o boleto confirma dias depois quando é compensado, e a cobrança mensal de uma assinatura acontece enquanto o seu cliente está dormindo. Sem webhook, o seu código precisaria consultar cada pedido pendente o tempo todo. Com webhook, ele só reage quando há o que reagir.

Webhook ou polling: qual usar?

A conta em escala: com 500 pedidos pendentes consultados a cada 30 segundos, o seu sistema faz 1,44 milhão de requisições por dia para descobrir algumas dezenas de pagamentos. Com webhook, são algumas dezenas de requisições, uma por evento. Polling ainda tem lugar, como rede de segurança para conciliar no fim do dia com GET /sales/unitary, mas não como fonte principal de verdade.

Mais definições do tema no glossário.

Como funciona o webhook de pagamento no HeroPay?

Do ponto de vista do dinheiro, o fluxo tem cinco passos:

1. Você cadastra a URL. Um POST /webhook por gatilho, dizendo qual evento quer ouvir e para onde mandar. Guarde o segredo de assinatura do webhook em variável de ambiente.
2. O comprador paga. Pelo link de pagamento ou pelo checkout, com Pix, cartão em até 12x ou boleto.
3. O HeroPay assina e envia. Calcula o HMAC SHA-256 do corpo com o seu segredo, coloca no header X-HeroPay-Signature e faz o POST JSON para a sua URL.
4. Você valida e responde 200. Recalcula a assinatura, confere se o evento já foi processado, responde 200 rápido e joga o trabalho pesado para uma fila.
5. Se falhar, o HeroPay tenta de novo. Qualquer resposta fora de 2xx (ou timeout) faz o evento ser reenviado automaticamente.

Quais eventos o webhook do HeroPay envia?

São 9 gatilhos, com os nomes exatos que você passa no campo trigger. Confira a grafia do gatilho de recusa: é payment_credit_cart_refused, com cart, não card. Esse é o nome como ele existe na plataforma, e escrever card devolve 422 ("Trigger is not included in the list").

Fonte: documentação de webhooks e API de webhooks. Verificado em set/2026.

O que o HeroPay não avisa por webhook (ainda)

Honestidade de dev para dev, para você não esperar um evento que não vem:

• Carrinho abandonado não é webhook. Os abandonos ficam disponíveis por consulta em GET /reports/tracking/abandoned_carts (com start_date e end_date). Para recuperar, agende uma consulta periódica e dispare a mensagem pelo seu CRM. Veja carrinhos.
• Não existe evento de Pix expirado nem de boleto vencido. Use a data que já vem no payload (payment_methods.pix.expiration_at e payment_methods.boleto.expiration_at) para agendar o seu próprio lembrete, ou consulte GET /reports/transaction/pending/* para ver o que está expirando.
• Não existe gatilho "todos os eventos". Cada webhook ouve um gatilho. Para ouvir os 9, cadastre 9 webhooks (podem apontar para a mesma URL).

Na prática, por código

curl -X POST "https://api.beta.heropay.tech/webhook" \
  -H "Authorization: Bearer $HEROPAY_JWT_TOKEN" \
  -H "Accept: application/vnd.herospark.com; version=1" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook": {
      "trigger": "spark_payment_confirmed",
      "webhook_url": "https://seuapp.com/webhooks/heropay",
      "request_method": "post"
    }
  }'

{
  "message": "Webhook created successfully",
  "data": {
    "id": 201738,
    "name": "Pagamento confirmado",
    "active": true,
    "created_at": "2025-08-28T07:21:35.464Z",
    "updated_at": "2025-08-28T07:21:35.464Z",
    "can_update": true,
    "configurations": {
      "url": "https://seuapp.com/webhooks/heropay",
      "request_method": "post"
    },
    "event": {
      "id": 122758,
      "trigger": "spark_payment_confirmed"
    }
  }
}

{
  "buyer": {
    "name": "Ana Souza",
    "email": "ana@exemplo.com",
    "phone": "(11) 98888-7777",
    "phone_raw": "11988887777",
    "document_id": "12345678909",
    "document_type": "cpf",
    "city": "São Paulo",
    "state": "SP",
    "district": "Pinheiros",
    "complement": "",
    "address": { "number": "100", "street": "Rua dos Pinheiros" }
  },
  "payment": {
    "id": "8812345",
    "date": "2026-09-23T10:12:44-03:00",
    "value": "97.00",
    "due_at": "",
    "method": "pix",
    "status": "paid",
    "net_value_cents": "9700"
  },
  "offer": {
    "title": "Plano Pro",
    "price": "97.00",
    "discount": "",
    "with_discount": "false",
    "discount_value": ""
  },
  "product": { "name": "Plano Pro" },
  "cart": { "src": "lancamento-setembro" },
  "subscription": {
    "id": "",
    "status": "",
    "expiration_at": "",
    "available_until": "",
    "next_invoice_at": ""
  },
  "installments": { "count": "1", "fees": "" },
  "payment_methods": {
    "pix": { "expiration_at": "2026-09-23T10:42:44-03:00" },
    "boleto": { "expiration_at": "" },
    "credit_card": { "refused_message": "" }
  }
}

import crypto from "node:crypto";

// Express com body cru (express.raw({ type: "application/json" }))
app.post("/webhooks/heropay", (req, res) => {
  const recebida = req.get("X-HeroPay-Signature") || "";
  const mac = crypto
    .createHmac("sha256", process.env.HEROPAY_WEBHOOK_SECRET)
    .update(req.body)
    .digest();

  // aceita hexadecimal ou base64; comparação em tempo constante
  const valida = [mac.toString("hex"), mac.toString("base64")].some(
    (esperada) =>
      esperada.length === recebida.length &&
      crypto.timingSafeEqual(Buffer.from(esperada), Buffer.from(recebida))
  );

  if (!valida) {
    return res.sendStatus(401);
  }

  const evento = JSON.parse(req.body);
  // deduplique antes de agir: o mesmo evento pode chegar mais de uma vez
  res.sendStatus(200);
});

import base64
import hashlib
import hmac
import json
import os

from flask import Flask, abort, request

app = Flask(__name__)
SEGREDO = os.environ["HEROPAY_WEBHOOK_SECRET"].encode()

@app.post("/webhooks/heropay")
def heropay_webhook():
    corpo = request.get_data()  # bytes crus, antes de qualquer parse
    recebida = request.headers.get("X-HeroPay-Signature", "")
    mac = hmac.new(SEGREDO, corpo, hashlib.sha256).digest()
    # aceita hexadecimal ou base64; comparação em tempo constante
    candidatas = [mac.hex(), base64.b64encode(mac).decode()]

    if not any(hmac.compare_digest(recebida, esperada) for esperada in candidatas):
        abort(401)

    evento = json.loads(corpo)
    # deduplique e enfileire; o trabalho pesado roda fora da requisição
    return "", 200

Por prompt: peça o webhook à sua ferramenta de IA

Cole https://heropay.tech/llms.txt na conversa com Claude, ChatGPT, Cursor, Lovable e outros, e a ferramenta passa a conhecer a API do HeroPay a partir das docs abertas. Aí o cadastro e a rota viram uma frase:

Com base em https://heropay.tech/llms.txt, escreva o curl que cadastra um
webhook de pagamento confirmado apontando para
https://seuapp.com/webhooks/heropay e a rota em Express que valida o
X-HeroPay-Signature com HMAC SHA-256 sobre o corpo bruto, deduplica por
gatilho + payment.id e responde 200 antes de liberar o acesso numa fila.

O código gerado usa o mesmo POST /webhook desta página. A chave de API fica no seu ambiente (variável HEROPAY_JWT_TOKEN), nunca colada no chat. Um MCP server oficial está em desenvolvimento; até lá, llms.txt, docs e API REST são o caminho que funciona hoje. Passo a passo em /integracoes/lovable.

Boas práticas: como receber webhook de pagamento sem liberar acesso errado

Responda 200 rápido e processe depois

O seu endpoint deve validar a assinatura, gravar o evento e responder 200 em milissegundos. Emitir nota, mandar e-mail e chamar outras APIs vai para uma fila (Sidekiq, BullMQ, Celery, SQS, o que você já usa). Endpoint que demora vira timeout, timeout vira retentativa, e retentativa vira o mesmo evento processado duas vezes.

Deduplique: o mesmo evento pode chegar duas vezes

A entrega de webhook é "pelo menos uma vez", não "exatamente uma vez": a retentativa automática pode entregar um evento que você já processou, por exemplo quando o seu 200 se perdeu na rede. O payload não traz um ID de evento próprio, então monte a chave de deduplicação com o que ele tem: gatilho + payment.id (e, nos gatilhos de assinatura, + subscription.status). Grave essa chave numa tabela com índice único antes de agir; se o insert falhar por duplicidade, responda 200 e não faça nada.

Seja idempotente em cada ação

Deduplicar protege a porta; idempotência protege a casa. Escreva cada ação para que rodar duas vezes dê o mesmo resultado: "definir acesso como ativo" em vez de "somar 30 dias", "criar nota se não existir nota para este payment.id" em vez de "criar nota". Se a deduplicação falhar um dia, o estrago é zero.

Valide o valor antes de liberar acesso

Assinatura válida prova que o evento veio do HeroPay. Não prova que é o evento que você esperava. Antes de liberar, confira no seu banco: o payment.status indica pago, o offer.title é o plano que o usuário escolheu e o payment.value bate com o preço que você cobra por ele. Um webhook de um produto de R$ 9,90 não pode liberar o plano anual de R$ 970. Para ações de alto valor, reconsulte a venda pela API (GET /sales/unitary com searchForPeopleWith e paymentStatus) antes de liberar.

Não dependa da ordem de chegada

Eventos podem chegar fora de ordem: um subscription_update pode chegar antes do spark_payment_confirmed da mesma cobrança, principalmente se um deles foi retentado. Trate cada evento como "o estado agora é X" e, quando a ordem importar, compare datas do payload (payment.date, subscription.next_invoice_at) antes de sobrescrever um estado mais novo com um mais antigo.

Proteja o endpoint e o segredo

Use HTTPS. Guarde o segredo em variável de ambiente, nunca no repositório. Isente a rota de webhook da proteção CSRF do seu framework (Rails, Django, Laravel), senão o POST legítimo é bloqueado. Rejeite com 401 qualquer requisição sem assinatura válida e não logue o corpo inteiro com dados pessoais do comprador.

Tenha um plano para o replay

A assinatura do HeroPay cobre o corpo da requisição. Não conte com um carimbo de tempo no header, como o t=... do Stripe-Signature, para barrar replay: uma requisição válida capturada poderia ser reenviada mais tarde com a mesma assinatura. A deduplicação por gatilho + payment.id já neutraliza esse replay: o evento repetido é descartado. Mais um motivo para nunca pular a deduplicação.

Casos de uso

SaaS com plano mensal de R$ 97

O micro-SaaS cria o link recorrente e ouve quatro gatilhos. subscription_activate cria o plano; spark_payment_confirmed renova o acesso a cada mensalidade; payment_credit_cart_refused manda um e-mail com o motivo da recusa e o link para trocar o cartão; subscription_cancel agenda o fim do acesso para o último dia pago. Com 300 assinantes, são cerca de 300 eventos de confirmação por mês e nenhuma consulta de polling. No cartão, cada mensalidade de R$ 97 deixa cerca de R$ 93,61 líquidos (tarifa de 3,49%); se o assinante migrar para o Pix, R$ 97 inteiros. Veja assinaturas e Pix Automático.

Curso ou infoproduto com lançamento

O produtor divulga o mesmo produto com ?src=instagram, ?src=youtube e ?src=email. Cada spark_payment_confirmed chega com cart.src, e uma planilha ou dashboard soma a receita por canal sem depender de pixel. O spark_payment_boleto_created dispara o boleto no WhatsApp na hora, e o payment_pix_created sem confirmação depois de alguns minutos vira lembrete. Veja link de pagamento.

Loja ou app com risco de chargeback

Num produto de R$ 297, um chargeback_request sem reação significa entregar o produto e perder o valor. O handler revoga o acesso, abre um ticket interno com os dados de buyer e payment e separa as evidências de uso para a contestação. O mesmo handler trata refunded para ajustar comissão e nota. Veja antifraude e segurança.

Limites e regras

• Um gatilho por webhook. Para ouvir os 9 eventos, cadastre 9 webhooks. Todos podem apontar para a mesma URL; uma rota por gatilho deixa o tipo do evento explícito no caminho.
• Sem ID de evento no payload. Deduplique por gatilho + payment.id, como descrito acima.
• Replay se barra na deduplicação. Não dependa de carimbo de tempo na assinatura.
• Sem evento de carrinho abandonado, Pix expirado ou boleto vencido. Use os endpoints de relatório para esses casos.
• Sem lista de IPs de origem publicada. Autentique pela assinatura, não pelo IP.
• Retentativa automática em qualquer resposta fora de 2xx. Não conte com um número fixo de tentativas: a conciliação diária com GET /sales/unitary pega o que escapar.
• Segredo é credencial. Trate o segredo do webhook como senha: variável de ambiente, fora do repositório e fora dos logs.
• Sandbox idêntico à produção. O payload que você testa em api.beta.heropay.tech é o mesmo que chega no ar; para ir para produção, troque a chave e a URL base.

Comece agora

Cadastre o primeiro webhook no sandbox em cinco minutos, sem cartão de crédito e sem fila de homologação.

Criar conta sandbox · Ler a documentação

Continue por aqui: Desenvolvedores · Link de pagamento · Pix · Assinaturas · Checkout · Segurança · MCP e IA · Preços · Glossário