Docs DM10

Webhooks para os clientes

O ChurchPay avisa o sistema de cada cliente, por um POST assinado, a cada mudança de estado de uma intenção de pagamento da Salva+ ou da maquininha: Pix pago, cartão confirmado, estorno, Pix vencido, cobrança recusada. Esta página é o contrato com quem recebe: o que chega, como conferir a assinatura e como recuperar o que se perdeu.

O sentido oposto, os avisos que a Canvi e a OWN mandam ao ChurchPay, está em Webhooks.

Cadastro

A URL é cadastrada pelo suporte, no ERP, para um cliente e um produto: salva (Salva+) ou pos (maquininha). Quem tem os dois produtos cadastra duas URLs, que podem ser o mesmo endereço. Cada URL pode receber todos os tipos de evento ou só alguns.

  • Só HTTPS na porta 443, sem usuário e senha na URL, num endereço público.
  • No cadastro saem duas chaves, uma única vez: o segredo (whsec_…), que assina os avisos, e a chave de conciliação (whkey_…), que dá acesso a GET /webhooks/events. Guarde as duas no cofre de segredos do seu sistema. Perdeu, o suporte gera outras.
  • Para testar a integração, o suporte manda um webhook.ping pelo ERP.

Requisição

POST na URL cadastrada, com Content-Type: application/json e estes headers:

HeaderValor
ChurchPay-Event-IdO id do evento. Igual em todas as tentativas.
ChurchPay-Event-TypeO tipo, por exemplo payment.confirmed.
ChurchPay-Delivery-IdO id da entrega a esta URL. Muda entre URLs, não entre tentativas.
ChurchPay-AttemptO número da tentativa, a partir de 1.
ChurchPay-Signaturet=<unix>,v1=<hex> (abaixo).
User-AgentChurchPay-Webhooks/1

Corpo

{
  "id": "6f1c2a54-9d1e-4f3b-8a51-0c2e7d9b1a44",
  "type": "payment.confirmed",
  "apiVersion": "2026-11",
  "occurredAt": "2026-11-17T17:00:00.123Z",
  "data": {
    "intent": {
      "id": "0b9b6c1e-4a52-4bb0-9a4e-5d3c2f1a7e10",
      "tenantId": "10001",
      "product": "salva",
      "kind": "dynamic",
      "method": "pix",
      "status": "confirmed",
      "amountCents": 5000
    },
    "payment": {
      "id": null,
      "amountCents": 5000,
      "acquirerRef": "E18236120202611171700s0123456789",
      "paidAt": "2026-11-17T17:00:00.000Z",
      "feeCents": null,
      "cardType": null,
      "installments": null,
      "payer": { "name": "Maria", "maskedCpf": "***456.789-**" }
    }
  }
}
CampoO que é
idO id do evento. Use para ignorar duplicatas.
occurredAtQuando a mudança aconteceu (ISO 8601, UTC).
data.intent.statusO estado da intenção no momento do evento, não o atual. No QR estático (kind: "static"), um pagamento não muda o estado: o QR segue created, ativo.
data.intent.amountCentsValor em centavos.
data.paymentnull nos eventos intent.*. No QR estático, id identifica cada pagamento.
data.payment.acquirerRefId do pagamento no provedor (o id_transacao do Pix, o id da transação no cartão).
data.payment.payerNome e CPF mascarado, quando conhecidos. O CPF completo nunca é enviado.

Tipos

TipoQuando
intent.createdA intenção foi criada (no Pix, antes do QR existir).
intent.failedA Canvi recusou criar o Pix.
intent.expiredVenceu sem pagamento.
intent.canceledCancelada pelo app antes da captura, ou QR estático substituído.
payment.confirmedPagamento confirmado. No QR estático, um por pagamento.
payment.reversedEstorno do cartão.
payment.feeA taxa chegou depois da confirmação; feeCents preenchido.
webhook.pingTeste pedido pelo suporte. data.intent e data.payment são null.

Uma intenção paga depois de intent.expired ainda gera payment.confirmed: se o dinheiro entrou, o pagamento vale.

Assinatura

ChurchPay-Signature: t=1795442400,v1=5f2b…c9

v1 é o HMAC-SHA256, em hexadecimal, de <t>.<corpo cru>, com o segredo inteiro (inclusive o prefixo whsec_) como chave. Para aceitar um aviso:

  1. Leia o corpo cru, os bytes como chegaram. Reserializar o JSON muda os bytes e a assinatura não bate.
  2. Recuse se t estiver a mais de 5 minutos do seu relógio (proteção contra reenvio de um aviso antigo).
  3. Calcule o HMAC e compare em tempo constante com cada v1 do header. Basta um bater.

Durante a troca de segredo, o header traz dois v1, um por segredo, por 24 horas. Configure o segredo novo assim que o suporte o entregar; o antigo para de assinar depois desse prazo.

Node.js (Express)

import crypto from 'node:crypto'
import express from 'express'

const SEGREDO = process.env.CHURCHPAY_WEBHOOK_SECRET // whsec_…

export function assinaturaValida(corpo, header, segredo, agora = Date.now()) {
  const partes = header.split(',').map((parte) => parte.split('='))
  const t = Number(partes.find(([chave]) => chave === 't')?.[1])
  if (!t || Math.abs(agora / 1000 - t) > 300) return false
  const esperado = crypto
    .createHmac('sha256', segredo)
    .update(`${t}.`)
    .update(corpo)
    .digest()
  return partes
    .filter(([chave]) => chave === 'v1')
    .some(([, valor]) => {
      const recebido = Buffer.from(valor ?? '', 'hex')
      return (
        recebido.length === esperado.length &&
        crypto.timingSafeEqual(recebido, esperado)
      )
    })
}

const app = express()

// express.raw: o corpo chega como Buffer, sem reserializar.
app.post('/churchpay', express.raw({ type: 'application/json' }), (req, res) => {
  if (!assinaturaValida(req.body, req.get('ChurchPay-Signature') ?? '', SEGREDO)) {
    return res.sendStatus(401)
  }
  const evento = JSON.parse(req.body.toString('utf8'))
  // Grave o evento (ignorando um evento.id já visto) e processe depois.
  res.sendStatus(204)
})

PHP

<?php
function assinatura_valida(string $corpo, string $header, string $segredo, ?int $agora = null): bool
{
    $t = null;
    $assinaturas = [];
    foreach (explode(',', $header) as $parte) {
        [$chave, $valor] = array_pad(explode('=', $parte, 2), 2, '');
        if ($chave === 't') $t = (int) $valor;
        if ($chave === 'v1') $assinaturas[] = $valor;
    }
    if (!$t || abs(($agora ?? time()) - $t) > 300) return false;
    $esperado = hash_hmac('sha256', $t . '.' . $corpo, $segredo);
    foreach ($assinaturas as $assinatura) {
        if (hash_equals($esperado, $assinatura)) return true;
    }
    return false;
}

$corpo = file_get_contents('php://input');
$header = $_SERVER['HTTP_CHURCHPAY_SIGNATURE'] ?? '';
if (!assinatura_valida($corpo, $header, getenv('CHURCHPAY_WEBHOOK_SECRET'))) {
    http_response_code(401);
    exit;
}
$evento = json_decode($corpo, true);
// Grave o evento (ignorando um $evento['id'] já visto) e processe depois.
http_response_code(204);

Python

import hashlib
import hmac
import time


def assinatura_valida(corpo: bytes, header: str, segredo: str, agora: "float | None" = None) -> bool:
    partes = [parte.split("=", 1) for parte in header.split(",") if "=" in parte]
    t = next((valor for chave, valor in partes if chave == "t"), None)
    if not t or not t.isdigit() or abs((agora or time.time()) - int(t)) > 300:
        return False
    esperado = hmac.new(segredo.encode(), f"{t}.".encode() + corpo, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(esperado, valor) for chave, valor in partes if chave == "v1")

O que o seu sistema precisa garantir

  • Responder 2xx em até 10 segundos e processar depois. Qualquer outra resposta, redirecionamento (3xx) ou demora conta como falha.
  • Ignorar duplicatas pelo id. A entrega é pelo menos uma vez: uma queda entre o envio e o registro da resposta faz o aviso sair de novo.
  • Não depender da ordem. Um payment.confirmed pode chegar antes do intent.created, se este falhou e foi retentado. Use occurredAt para descartar um evento mais antigo que o último aplicado, ou consulte a intenção.
  • Aceitar campos novos. Campos podem ser acrescentados sem mudar apiVersion; remover um campo ou mudar o sentido dele muda a versão.

Retentativas

Sem 2xx, o aviso é reenviado em 1 min, 5 min, 30 min, 2 h, 6 h e 24 h, cada espera com até 10% a mais (sete tentativas, cerca de 33 horas). Depois disso a entrega é dada como falha, e só sai de novo por reenvio do suporte ou pela conciliação.

Com 50 falhas seguidas, a URL é parada: os avisos continuam sendo registrados, mas não saem até o suporte reativá-la. Ao reativar, eles saem na ordem em que foram criados.

Conciliação

GET /webhooks/events devolve os mesmos corpos que a URL recebeu, ou deveria ter recebido, nos últimos 30 dias, das mais antigas para as mais novas. Byte a byte o que foi assinado e enviado.

curl -H "Authorization: Bearer whkey_…" \
  "https://<endereço da API do ChurchPay>/webhooks/events?limit=100"
{
  "success": true,
  "data": [{ "id": "6f1c…", "type": "payment.confirmed", "apiVersion": "2026-11", "occurredAt": "…", "data": { "intent": { … }, "payment": { … } } }],
  "next": "MjAyNi0xMS0xN1QxNzowMDowMC4xMjNafDZmMWM…"
}
ParâmetroUso
afterO next da página anterior. Opaco: guarde e mande de volta.
limitDe 1 a 500 (padrão 100).
typeSó um tipo de evento.
intentIdSó os eventos de uma intenção.

next vem null na última página. Um sistema que sincroniza por esta rota a cada poucos minutos, guardando o último next, fica correto mesmo se todos os webhooks se perderem; o webhook passa a ser o atalho para saber na hora. Limite: 60 leituras por minuto por URL.

Nesta página