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 aGET /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.pingpelo ERP.
Requisição
POST na URL cadastrada, com Content-Type: application/json e estes headers:
| Header | Valor |
|---|---|
ChurchPay-Event-Id | O id do evento. Igual em todas as tentativas. |
ChurchPay-Event-Type | O tipo, por exemplo payment.confirmed. |
ChurchPay-Delivery-Id | O id da entrega a esta URL. Muda entre URLs, não entre tentativas. |
ChurchPay-Attempt | O número da tentativa, a partir de 1. |
ChurchPay-Signature | t=<unix>,v1=<hex> (abaixo). |
User-Agent | ChurchPay-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-**" }
}
}
}| Campo | O que é |
|---|---|
id | O id do evento. Use para ignorar duplicatas. |
occurredAt | Quando a mudança aconteceu (ISO 8601, UTC). |
data.intent.status | O 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.amountCents | Valor em centavos. |
data.payment | null nos eventos intent.*. No QR estático, id identifica cada pagamento. |
data.payment.acquirerRef | Id do pagamento no provedor (o id_transacao do Pix, o id da transação no cartão). |
data.payment.payer | Nome e CPF mascarado, quando conhecidos. O CPF completo nunca é enviado. |
Tipos
| Tipo | Quando |
|---|---|
intent.created | A intenção foi criada (no Pix, antes do QR existir). |
intent.failed | A Canvi recusou criar o Pix. |
intent.expired | Venceu sem pagamento. |
intent.canceled | Cancelada pelo app antes da captura, ou QR estático substituído. |
payment.confirmed | Pagamento confirmado. No QR estático, um por pagamento. |
payment.reversed | Estorno do cartão. |
payment.fee | A taxa chegou depois da confirmação; feeCents preenchido. |
webhook.ping | Teste 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…c9v1 é o HMAC-SHA256, em hexadecimal, de <t>.<corpo cru>, com o segredo inteiro (inclusive o
prefixo whsec_) como chave. Para aceitar um aviso:
- Leia o corpo cru, os bytes como chegaram. Reserializar o JSON muda os bytes e a assinatura não bate.
- Recuse se
testiver a mais de 5 minutos do seu relógio (proteção contra reenvio de um aviso antigo). - Calcule o HMAC e compare em tempo constante com cada
v1do 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.confirmedpode chegar antes dointent.created, se este falhou e foi retentado. UseoccurredAtpara 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âmetro | Uso |
|---|---|
after | O next da página anterior. Opaco: guarde e mande de volta. |
limit | De 1 a 500 (padrão 100). |
type | Só um tipo de evento. |
intentId | Só 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.