Pular para o conteúdo principal

Webhooks

Os webhooks permitem que uma igreja envie notificações em tempo real para ferramentas de terceiros — plataformas de automação (Zapier, Make, n8n), CRMs, sistemas contábeis ou qualquer serviço que aceite um HTTP POST. Quando uma pessoa, um grupo ou uma família é alterado no B1, o B1 envia um payload JSON assinado para cada URL inscrita nesse evento.

Antes de começar

  • Um administrador da igreja com a permissão Editar Configurações da Igreja registra e gerencia os webhooks
  • Seu endpoint de recebimento precisa estar acessível por HTTPS em um endereço público
  • Tenha uma forma segura de armazenar o segredo de assinatura — ele é exibido apenas uma vez

Visão geral​

Os webhooks são somente de saída: o B1 chama o seu endpoint, e você não chama o B1. Cada webhook é uma assinatura por igreja, composta por uma URL de destino, um segredo de assinatura e uma lista de eventos inscritos.

A entrega usa uma fila de saída durável: quando um evento inscrito ocorre, o B1 registra uma linha de entrega e um worker em segundo plano envia o POST em até cerca de um minuto. Entregas com falha são repetidas com backoff exponencial. Nada é perdido se uma entrega estiver lenta ou se o seu endpoint estiver temporariamente indisponível.

Registrando um webhook​

No B1Admin​

Acesse Configurações → Desenvolvedor → Webhooks → Novo Webhook. Informe um nome, a URL do payload e selecione os eventos para assinar. Ao salvar, o segredo de assinatura é exibido uma única vez — copie-o imediatamente e armazene-o junto com a sua integração. Ele nunca mais será exibido (você pode gerar um novo depois, mas não pode recuperar o original).

Via API​

Todos os endpoints ficam sob o caminho base do módulo Membership /membership/webhooks e exigem um JWT de um administrador da igreja com a permissão Settings / Edit, ou uma chave de API gerada com o escopo settings:write. As mesmas rotas aceitam ambos. É isso que permite ao Zapier e ao Make registrar webhooks em nome da igreja quando um Zap ou cenário é ativado.

POST /membership/webhooks
Authorization: Bearer <jwt>
Content-Type: application/json

{
"name": "Zapier — new members",
"url": "https://hooks.zapier.com/hooks/catch/123/abc",
"events": ["person.created", "person.updated", "group.member.added"]
}

A resposta de criação — e somente a resposta de criação — inclui o secret:

{
"id": "a1b2c3d4e5f",
"name": "Zapier — new members",
"url": "https://hooks.zapier.com/hooks/catch/123/abc",
"events": ["person.created", "person.updated", "group.member.added"],
"active": true,
"secret": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822c"
}
Método e caminhoFinalidade
GET /membership/webhooksLista os webhooks da igreja (sem o segredo)
GET /membership/webhooks/eventsO catálogo de nomes de eventos válidos
GET /membership/webhooks/:idCarrega um webhook
POST /membership/webhooksCria (sem id) ou atualiza (com id)
POST /membership/webhooks/:id/regenerate-secretGera um novo segredo de assinatura; retorna o novo valor uma única vez
DELETE /membership/webhooks/:idExclui um webhook
GET /membership/webhooks/:id/deliveriesTentativas de entrega recentes de um webhook
GET /membership/webhooks/deliveries/:deliveryIdPayload e resposta completos de uma entrega
POST /membership/webhooks/deliveries/:deliveryId/redeliverColoca uma entrega novamente na fila

Catálogo de eventos​

Os nomes dos eventos seguem o padrão {entity}.{action}. Obtenha a lista atualizada em GET /membership/webhooks/events.

EventoDisparado quando
person.createdUma pessoa é adicionada
person.updatedO registro de uma pessoa é alterado
person.destroyedUma pessoa é excluída
household.createdUma família é adicionada
household.updatedUma família é alterada
household.destroyedUma família é excluída
group.createdUm grupo é adicionado
group.updatedUm grupo é alterado
group.destroyedUm grupo é excluído
group.member.addedUma pessoa é adicionada a um grupo
group.member.removedUma pessoa é removida de um grupo
donation.createdUma doação é registrada — lançamento manual, online ou a transição de pendente → concluída
donation.updatedUm registro de doação é editado
attendance.recordedUma presença é registrada (lançamento manual ou check-in)
session.createdUma nova sessão de presença é criada (manualmente ou automaticamente no primeiro check-in)
form.submission.createdUm formulário é enviado
event.createdUm evento do calendário é adicionado
event.updatedUm evento do calendário é editado
event.destroyedUm evento do calendário é excluído

Formato do payload​

Cada entrega é um POST HTTP com um corpo JSON e estes cabeçalhos:

CabeçalhoDescrição
Content-TypeSempre application/json
X-B1-EventO nome do evento, por exemplo person.created
X-B1-Delivery-IdIdentificador único desta tentativa de entrega — use-o para deduplicar
X-B1-SignatureAssinatura HMAC-SHA256 do corpo bruto (veja abaixo)
X-B1-TimestampSegundos desde a época Unix em que a requisição foi enviada
User-AgentB1-Webhooks/1.0

O corpo envolve o recurso alterado em um pequeno envelope:

{
"event": "person.created",
"churchId": "AbC123XyZ90",
"occurredAt": "2026-05-17T14:32:08.114Z",
"data": {
"id": "Pq7Rs2Tu4Vw",
"churchId": "AbC123XyZ90",
"name": { "display": "Jordan Rivera", "first": "Jordan", "last": "Rivera" },
"contactInfo": { "email": "jordan@example.com" }
}
}

Para eventos *.destroyed, data contém apenas o id e o churchId do registro excluído.

Eventos cujos payloads referenciam outros registros por id também incluem nomes legíveis, resolvidos no momento da entrega: personName e groupName nos eventos de associação a grupos, personName nos eventos de presença, doação e associação a listas, groupName em session.created, e formName (além de personName, quando o envio está vinculado a uma pessoa) em form.submission.created.

Tipos de conector​

O formato de entrega padrão é o envelope JSON acima — connectorType: "standard". Para o Slack e o Discord, o mesmo mecanismo de webhook envia uma mensagem no formato de chat, que esses serviços aceitam diretamente:

connectorTypeCorpo enviadoUse quando
"standard" (padrão)Envelope {event, churchId, occurredAt, data}, assinadoVocê está criando a sua própria integração, ou apontando para Zapier / Make / um servidor personalizado
"slack"{ "text": "💝 New donation: $50.00" }Você está enviando diretamente para uma URL de Incoming Webhook do Slack
"discord"{ "content": "💝 New donation: $50.00" }Você está enviando diretamente para uma URL de webhook de canal do Discord
"mailchimp"n/a — o conector chama a própria API do MailchimpVocê quer sincronização de audiência sem nenhuma URL para hospedar

O tipo de conector é definido na lista suspensa Tipo de conector no editor de webhooks, ou pelo connectorType no corpo de POST /membership/webhooks. O cabeçalho X-B1-Signature assinado continua sendo enviado nas entregas para Slack/Discord (eles o ignoram sem problemas), então voltar um webhook para standard depois não exige nova assinatura.

Slack e Discord são apenas reformatações do corpo — o mecanismo ainda envia o POST para a URL fornecida pela igreja. mailchimp é o primeiro conector que gerencia a própria troca HTTP: para cada evento, ele faz requisições autenticadas de upsert/arquivamento/tag na API do Mailchimp (MailchimpConnector.deliver), e suas credenciais ({apiKey, audienceId}) são armazenadas criptografadas com AES em webhooks.connectorConfig, somente gravação pela API. Webhooks do Mailchimp aceitam apenas eventos de pessoa, de membro de grupo e de membro de lista; a rota de salvamento verifica a chave e a audiência no Mailchimp antes de aceitá-las. As linhas de entrega armazenam o envelope padrão, então o log de entregas mostra o que o B1 recebeu junto com a resposta do Mailchimp. Situações sem mapeamento (pessoa sem e-mail, evento sem mapeamento) são concluídas como bem-sucedidas com um corpo de resposta Skipped:, em vez de consumir novas tentativas.

Entregas de teste​

Todo editor de webhook tem um botão Enviar evento de teste — a chamada de API correspondente é POST /membership/webhooks/:id/test. A rota de teste monta um payload sintético para o primeiro evento inscrito, despacha-o de forma síncrona pelo caminho real de entrega assinada (e pelo formatForConnector para Slack/Discord), e retorna a linha de entrega resultante, incluindo responseStatus e responseBody. Use-a para confirmar a conectividade e o tratamento da assinatura antes de ativar a integração de verdade. Para webhooks mailchimp, o teste verifica as credenciais armazenadas na API do Mailchimp (um evento sintético gravaria um assinante falso na audiência real da igreja) e retorna um resultado no formato de entrega, sem criar uma linha.

Verificando assinaturas​

Sempre verifique o X-B1-Signature antes de confiar em um payload. A assinatura é sha256= seguido do HMAC-SHA256 em hexadecimal do corpo bruto da requisição, usando o seu segredo de assinatura como chave. Calcule-a sobre os bytes recebidos — não serialize novamente o JSON já analisado.

Node.js

const crypto = require("crypto");

function isValid(rawBody, signatureHeader, secret) {
const expected = "sha256=" + crypto.createHmac("sha256", secret).update(rawBody, "utf8").digest("hex");
const a = Buffer.from(expected);
const b = Buffer.from(signatureHeader || "");
return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Python

import hashlib, hmac

def is_valid(raw_body: bytes, signature_header: str, secret: str) -> bool:
expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, signature_header or "")

PHP

function isValid(string $rawBody, string $signatureHeader, string $secret): bool {
$expected = "sha256=" . hash_hmac("sha256", $rawBody, $secret);
return hash_equals($expected, $signatureHeader ?? "");
}

Rejeite qualquer requisição cuja assinatura não corresponda. Opcionalmente, rejeite também requisições cujo X-B1-Timestamp tenha mais de alguns minutos, para limitar a janela de reenvio malicioso (replay).

Suporte ao SDK​

Para Node.js, o @churchapps/integration-sdk inclui um verificador tipado e um middleware para Express que cuida, para você, da captura do corpo bruto, da verificação da assinatura e da análise do envelope:

import express from "express";
import { b1WebhookMiddleware } from "@churchapps/integration-sdk";

const app = express();
// Capture the raw body before JSON parsing — required so the signature still verifies.
app.use(express.json({ verify: (req, _res, buf) => { (req as any).rawBody = buf; } }));

app.post("/webhooks/b1", b1WebhookMiddleware({ secret: process.env.B1_WEBHOOK_SECRET! }), (req, res) => {
const env = req.b1Webhook!;
switch (env.event) {
case "donation.created": console.log("new gift", env.data.amount); break;
}
res.sendStatus(200);
});

O SDK também expõe WebhookVerifier.verify(secret, rawBody, signatureHeader) para runtimes que não são Express (funções serverless, Fastify, etc.). Consulte o pacote no npm.

Entrega e novas tentativas​

Seu endpoint deve responder com status 2xx o mais rápido possível — idealmente depois de apenas enfileirar o trabalho, e não depois de processá-lo. Qualquer resposta que não seja 2xx, falha de conexão ou resposta mais lenta que 10 segundos conta como entrega com falha.

Entregas com falha são repetidas com backoff exponencial — 16 tentativas em cerca de 5 dias. O intervalo começa em 1 minuto, passa por horas e chega a intervalos de até 3 dias nas últimas tentativas. Após a 16ª tentativa falha, a entrega é marcada como exhausted (esgotada) e abandonada.

A entrega é pelo menos uma vez: uma entrega pode chegar mais de uma vez (por exemplo, se o seu endpoint tiver sucesso mas a resposta se perder). Use o cabeçalho X-B1-Delivery-Id para deduplicar — processe cada id apenas uma vez e trate as repetições como operações sem efeito.

Desativação automática​

Se um webhook produzir três entregas esgotadas consecutivas, o B1 o desativa automaticamente. Corrija o seu endpoint e, em seguida, reative o webhook no B1Admin (ou via POST /membership/webhooks com "active": true).

Inspecionando e reenviando​

O editor de webhooks no B1Admin mostra uma tabela de Entregas recentes — evento, status, número de tentativas, código de resposta e data/hora. Ao selecionar uma linha, você vê o payload completo que foi enviado e a resposta recebida.

Use Reenviar para colocar novamente na fila qualquer entrega anterior com o payload original — útil após corrigir um bug no seu endpoint, ou para reprocessar eventos que o seu endpoint deixou de receber enquanto estava indisponível.

Requisitos de URL​

Como as URLs de webhook são fornecidas pela igreja, o B1 aplica proteções contra falsificação de requisições do lado do servidor (SSRF). Uma URL de webhook é rejeitada — no registro e novamente verificada antes de cada entrega — se:

  • não usar https
  • apontar para localhost, um nome de host .local / .internal, ou
  • resolver para um endereço IP privado, de loopback, link-local ou de metadados de nuvem

Seu endpoint precisa ser um serviço HTTPS acessível publicamente.