Mergeți la conținut principal

Webhookuri

Webhookurile permit unei biserici să trimită notificări în timp real către instrumente de la terți: platforme de automatizare (Zapier, Make, n8n), CRM-uri, sisteme contabile sau orice serviciu care acceptă un HTTP POST. Când o persoană, un grup sau o gospodărie se modifică în B1, B1 trimite un payload JSON semnat către fiecare URL abonat la acel eveniment.

Înainte de a începe

  • Un administrator al bisericii cu permisiunea Edit Church Settings înregistrează și gestionează webhookurile
  • Endpoint-ul de primire trebuie să fie accesibil prin HTTPS, la o adresă publică
  • Pregătiți o modalitate de a stoca în siguranță secretul de semnare — acesta este afișat o singură dată

Prezentare generală​

Webhookurile sunt doar pentru trafic de ieșire: B1 apelează endpoint-ul dvs., dvs. nu apelați B1. Fiecare webhook este un abonament specific bisericii, format dintr-o adresă URL de destinație, un secret de semnare și o listă de evenimente la care se abonează.

Livrarea folosește un outbox durabil: când are loc un eveniment la care există un abonament, B1 înregistrează un rând de livrare, iar un proces de fundal trimite payload-ul prin POST în aproximativ un minut. Livrările eșuate sunt reîncercate cu backoff exponențial. Nimic nu se pierde dacă o livrare este lentă sau dacă endpoint-ul dvs. este indisponibil pentru scurt timp.

Înregistrarea unui webhook​

În B1Admin​

Mergeți la Settings → Developer → Webhooks → New Webhook. Introduceți un nume, adresa URL pentru payload și selectați evenimentele la care doriți să vă abonați. La salvare, secretul de semnare este afișat o singură dată — copiați-l imediat și stocați-l împreună cu integrarea. Nu va mai fi afișat niciodată (îl puteți roti ulterior, dar nu puteți recupera valoarea originală).

Prin API​

Toate endpoint-urile se află sub calea de bază a modulului Membership, /membership/webhooks, și necesită fie un JWT de la un administrator al bisericii cu permisiunea Settings / Edit, fie o cheie API creată cu scope-ul settings:write. Aceleași rute acceptă ambele variante. Acest lucru permite Zapier și Make să înregistreze webhookuri în numele bisericii atunci când un Zap sau un scenariu este activat.

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"]
}

Răspunsul la creare — și doar răspunsul la creare — include 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"
}
Metodă și caleScop
GET /membership/webhooksListează webhookurile bisericii (secretul este omis)
GET /membership/webhooks/eventsCatalogul numelor de evenimente valide
GET /membership/webhooks/:idÎncarcă un webhook
POST /membership/webhooksCreează (fără id) sau actualizează (cu id)
POST /membership/webhooks/:id/regenerate-secretRotește secretul de semnare; returnează noua valoare o singură dată
DELETE /membership/webhooks/:idȘterge un webhook
GET /membership/webhooks/:id/deliveriesÎncercările recente de livrare pentru un webhook
GET /membership/webhooks/deliveries/:deliveryIdPayload-ul complet și răspunsul pentru o livrare
POST /membership/webhooks/deliveries/:deliveryId/redeliverPune din nou în coadă o livrare

Catalogul de evenimente​

Numele evenimentelor urmează modelul {entity}.{action}. Obțineți lista actualizată de la GET /membership/webhooks/events.

EvenimentSe declanșează când
person.createdO persoană este adăugată
person.updatedÎnregistrarea unei persoane este modificată
person.destroyedO persoană este ștearsă
household.createdO gospodărie este adăugată
household.updatedO gospodărie este modificată
household.destroyedO gospodărie este ștearsă
group.createdUn grup este adăugat
group.updatedUn grup este modificat
group.destroyedUn grup este șters
group.member.addedO persoană este adăugată într-un grup
group.member.removedO persoană este eliminată dintr-un grup
donation.createdO donație este înregistrată — introdusă manual, online sau la trecerea din pending → complete
donation.updatedO înregistrare de donație este editată
attendance.recordedO prezență este înregistrată (introdusă manual sau prin check-in)
session.createdO nouă sesiune de prezență este creată (manual sau automat la primul check-in)
form.submission.createdUn formular este trimis
event.createdUn eveniment din calendar este adăugat
event.updatedUn eveniment din calendar este editat
event.destroyedUn eveniment din calendar este șters

Formatul payload-ului​

Fiecare livrare este un POST HTTP cu un corp JSON și următoarele anteturi:

AntetDescriere
Content-TypeÎntotdeauna application/json
X-B1-EventNumele evenimentului, de exemplu person.created
X-B1-Delivery-IdIdentificator unic pentru această încercare de livrare — folosiți-l pentru a elimina duplicatele
X-B1-SignatureSemnătura HMAC-SHA256 a corpului brut (vezi mai jos)
X-B1-TimestampNumărul de secunde Unix epoch la care a fost trimisă cererea
User-AgentB1-Webhooks/1.0

Corpul încapsulează resursa modificată într-un mic 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" }
}
}

Pentru evenimentele *.destroyed, data conține doar id și churchId ale înregistrării șterse.

Evenimentele ale căror payload-uri fac referire la alte înregistrări prin id includ și nume ușor de citit, rezolvate în momentul livrării: personName și groupName pentru evenimentele de apartenență la grup, personName pentru evenimentele de prezență, donație și apartenență la liste, groupName pentru session.created și formName (plus personName când trimiterea este legată de o persoană) pentru form.submission.created.

Tipuri de conectori​

Formatul implicit de livrare este envelope-ul JSON de mai sus — connectorType: "standard". Pentru Slack și Discord, același motor de webhook trimite în schimb un mesaj de tip chat, pe care aceste servicii îl acceptă direct:

connectorTypeCorp trimisUtilizați atunci când
"standard" (implicit)Envelope-ul {event, churchId, occurredAt, data}, semnatScrieți propria integrare sau indicați către Zapier / Make / un server personalizat
"slack"{ "text": "💝 New donation: $50.00" }Trimiteți direct către un URL de Incoming Webhook din Slack
"discord"{ "content": "💝 New donation: $50.00" }Trimiteți direct către un URL de webhook al unui canal Discord
"mailchimp"n/a — conectorul apelează singur API-ul MailchimpDoriți sincronizarea audienței fără un URL pe care să îl găzduiți

Tipul de conector se setează din lista Connector Type din editorul de webhook sau prin connectorType în corpul POST /membership/webhooks. Antetul semnat X-B1-Signature este trimis în continuare pentru livrările către Slack și Discord (ele îl ignoră fără efecte), astfel încât, dacă reveniți ulterior la standard, nu este nevoie de o nouă semnare.

Slack și Discord reprezintă doar o restructurare a corpului — motorul trimite în continuare prin POST către URL-ul furnizat de biserică. mailchimp este primul conector care gestionează singur schimbul HTTP: pentru fiecare eveniment, emite cereri autentificate de tip upsert/archive/tag către API-ul Mailchimp (MailchimpConnector.deliver), iar credențialele sale ({apiKey, audienceId}) sunt stocate criptate AES în webhooks.connectorConfig, fiind accesibile doar la scriere prin API. Webhookurile Mailchimp acceptă doar evenimente de tip persoană, membru de grup și membru de listă; ruta de salvare verifică cheia și audiența în Mailchimp înainte de a accepta configurația. Rândurile de livrare stochează envelope-ul standard, astfel încât jurnalul de livrări arată ce a văzut B1 alături de răspunsul Mailchimp. Situațiile nemapate (persoană fără e-mail, eveniment fără mapare) se finalizează ca reușite, cu un corp de răspuns Skipped:, în loc să consume reîncercări.

Livrări de test​

Fiecare editor de webhook are un buton Send Test Event — apelul API corespunzător este POST /membership/webhooks/:id/test. Ruta de test construiește un payload sintetic pentru primul eveniment abonat, îl trimite sincron prin calea reală de livrare semnată (și prin formatForConnector pentru Slack/Discord) și returnează rândul de livrare rezultat, inclusiv responseStatus și responseBody. Folosiți-o pentru a confirma conectivitatea și gestionarea semnăturii înainte de a activa integrarea pentru date reale. Pentru webhookurile mailchimp, testul verifică în schimb credențialele stocate față de API-ul Mailchimp (un eveniment sintetic ar scrie un abonat fals în audiența reală a bisericii) și returnează un rezultat de tip livrare, fără a crea un rând.

Verificarea semnăturilor​

Verificați întotdeauna X-B1-Signature înainte de a avea încredere într-un payload. Semnătura este sha256= urmat de HMAC-SHA256 în format hexazecimal al corpului brut al cererii, cu cheia secretului de semnare. Calculați-o pe octeții primiți — nu re-serializați JSON-ul parsat.

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 ?? "");
}

Respingeți orice cerere a cărei semnătură nu se potrivește. Opțional, respingeți și cererile al căror X-B1-Timestamp are mai mult de câteva minute, pentru a limita ferestrele de reluare a cererilor.

Suport SDK​

Pentru Node.js, @churchapps/integration-sdk include un verificator tipizat și un middleware pentru Express, care se ocupă de capturarea corpului brut, verificarea semnăturii și parsarea envelope-ului:

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);
});

SDK-ul expune și WebhookVerifier.verify(secret, rawBody, signatureHeader) pentru runtime-uri care nu sunt Express (funcții serverless, Fastify etc.). Consultați pachetul pe npm.

Livrare și reîncercări​

Endpoint-ul dvs. ar trebui să răspundă cu un status 2xx cât mai repede posibil — idealmente după ce a pus în coadă doar lucrul de făcut, nu după ce l-a procesat. Orice răspuns non-2xx, o eroare de conexiune sau un răspuns mai lent de 10 secunde este considerat livrare eșuată.

Livrările eșuate sunt reîncercate cu backoff exponențial — 16 încercări în aproximativ 5 zile. Intervalul crește de la 1 minut, trecând prin ore, până la pauze de 3 zile pentru ultimele încercări. După a 16-a încercare eșuată, livrarea este marcată ca exhausted și abandonată.

Livrarea este cel puțin o dată: o livrare poate ajunge de mai multe ori (de exemplu, dacă endpoint-ul dvs. reușește, dar răspunsul se pierde). Folosiți antetul X-B1-Delivery-Id pentru a elimina duplicatele — procesați fiecare id o singură dată și tratați repetările ca operațiuni fără efect.

Dezactivarea automată​

Dacă un webhook produce trei livrări epuizate consecutive, B1 îl dezactivează automat. Remediați endpoint-ul, apoi reactivați webhook-ul în B1Admin (sau prin POST /membership/webhooks cu "active": true).

Inspectarea și retrimiterea​

Editorul de webhook din B1Admin afișează un tabel Recent Deliveries — eveniment, status, numărul de încercări, codul de răspuns și data/ora. Selectarea unui rând afișează payload-ul complet trimis și răspunsul primit.

Folosiți Redeliver pentru a pune din nou în coadă orice livrare anterioară, cu payload-ul original — util după remedierea unui bug în endpoint-ul dvs. sau pentru a recupera evenimente pe care endpoint-ul nu le-a primit cât timp a fost indisponibil.

Cerințe privind adresa URL​

Deoarece adresele URL ale webhookurilor sunt furnizate de biserică, B1 aplică protecții împotriva falsificării cererilor pe partea serverului (SSRF). O adresă URL de webhook este respinsă — la înregistrare și din nou înainte de fiecare livrare — dacă:

  • nu folosește https
  • indică spre localhost, un nume de gazdă .local / .internal sau
  • se rezolvă la o adresă IP privată, de loopback, link-local sau de metadate ale furnizorului de cloud

Endpoint-ul dvs. trebuie să fie un serviciu HTTPS accesibil public.