Webhooks

O CarecaPay chama a SUA API quando uma cobrança é paga. Configure uma URL no painel e reaja aos eventos em tempo real.

Configure a URL no painel, em Webhooks. Quando uma cobrança sua for paga, fazemos um POST nessa URL com o evento charge.paid e a cobrança completa no corpo — sua aplicação libera o pedido na hora, sem ficar consultando a API.

Configurando

No painel, abra Webhooks e informe a URL HTTPS da sua API (ex.: https://sua-api.com/webhooks/carecapay).
Guarde o segredo (ccp_whsec_...) exibido — usado nos dois mecanismos de verificação abaixo.
Clique em "Enviar evento de teste" para validar a recepção de ponta a ponta.

O que você recebe

POST na sua URL

{
  "id": "evt_9c41b2d7",
  "type": "charge.paid",
  "created_at": "2026-07-10T12:03:11Z",
  "data": {
    "id": "txn_8f2c1a9b",
    "status": "paid",
    "method": "pix",
    "amount_cents": 1990,
    "currency": "BRL",
    "qr_code": "00020126580014br.gov.bcb.pix...",
    "qr_code_base64": "iVBORw0KGgoAAAANSUhEUgAA...",
    "provider_charge_id": "b6f0e3...",
    "external_reference": "order_42",
    "created_at": "2026-07-10T12:00:00Z",
    "paid_at": "2026-07-10T12:03:11Z"
  }
}

Parâmetro	Tipo	Descrição
`X-CarecaPay-Event`	header	O tipo do evento (charge.paid ou test).
`X-CarecaPay-Signature`	header	t=<unix>,v1=<hmac> — assinatura HMAC-SHA256 do corpo. Recomendado.
`X-CarecaPay-Token`	header	O seu segredo (ccp_whsec_...) cru. Alternativa mais simples, sem HMAC.

Eventos disponíveis

charge.paid — a cobrança foi paga (no sandbox, via simulate-payment; em produção, com a confirmação do Banco).
test — evento disparado pelo botão de teste do painel, para validar sua integração.

Validando a entrega

Toda entrega traz DOIS mecanismos — use o que preferir. Com um SDK oficial (Node, PHP ou Python), verificar a assinatura é uma chamada; veja a seção Webhooks de cada SDK. Sem SDK, dá pra calcular o HMAC na mão (recomendado) ou comparar o token cru (mais simples, exige HTTPS).

Node.js — HMAC (recomendado, sem SDK)

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyCarecaPay(rawBody, signatureHeader, secret) {
  const { t, v1 } = Object.fromEntries(
    signatureHeader.split(",").map((part) => part.split("=")),
  );
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false; // anti-replay

  const expected = createHmac("sha256", secret)
    .update(`${t}.${rawBody}`)
    .digest("hex");
  return timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

Verifique a assinatura usando o CORPO CRU da requisição (antes de qualquer parse). Frameworks que re-serializam o JSON mudam os bytes e invalidam o HMAC.

Node.js — token (mais simples, sem HMAC)

export function isFromCarecaPay(req, secret) {
  return req.get("X-CarecaPay-Token") === secret; // ccp_whsec_... do painel
}

O token cru não detecta corpo adulterado nem entrega repetida — use HTTPS na sua URL de webhook sempre, e prefira a assinatura HMAC quando possível.

Entrega, retries e idempotência

Responda 2xx rápido (menos de 10s) e processe o evento de forma assíncrona se precisar.
Se sua API não responder 2xx, tentamos de novo com backoff (30s, 2min, 10min, 30min — 5 tentativas no total).
Retries significam que você pode receber o MESMO evento mais de uma vez: use o id (evt_...) para deduplicar.
O log de entregas (com status e tentativas) fica no painel, em Webhooks.