Пријавите се на главни садржај

Вебхукови

Вебхукови омогућавају цркви да у реалном времену шаље обавештења алатима трећих страна: платформама за аутоматизацију (Zapier, Make, n8n), CRM системима, рачуноводственим системима или било чему што прихвата HTTP POST захтев. Када се особа, група или домаћинство промене у B1, B1 шаље потписани JSON садржај на сваку URL адресу која је претплаћена на тај догађај.

Пре почетка

  • Администратор цркве са дозволом Edit Church Settings региструје и управља вебхуковима
  • Ваша крајња тачка за пријем мора бити доступна преко HTTPS-а на јавној адреси
  • Припремите начин за безбедно чување тајног кључа за потпис, јер се приказује само једном

Преглед​

Вебхукови су само одлазни: B1 позива вашу крајњу тачку, а ви не позивате B1. Сваки вебхук је претплата по цркви која се састоји од одредишне URL адресе, тајног кључа за потпис и листе претплаћених догађаја.

Испорука користи трајни излазни ред (durable outbox). Када се догоди претплаћени догађај, B1 бележи ред испоруке, а позадински процес га шаље у року од око минут. Неуспеле испоруке се понављају уз експоненцијално повећавање интервала. Ништа се не губи ако је испорука спора или је ваша крајња тачка накратко недоступна.

Регистровање вебхука​

У B1Admin-у​

Идите на Settings → Developer → Webhooks → New Webhook (Подешавања → Програмер → Вебхукови → Нови вебхук). Унесите назив и URL адресу за садржај, па изаберите догађаје на које желите да се претплатите. Након чувања, тајни кључ за потпис се приказује једном. Одмах га копирајте и сачувајте уз своју интеграцију. Више се неће приказивати. Касније га можете променити, али оригинални кључ не можете поново да преузмете.

Преко API-ја​

Све крајње тачке се налазе испод основне путање модула Membership, /membership/webhooks. Захтевају или JWT токен администратора цркве са дозволом Settings / Edit, или API кључ направљен са опсегом settings:write. Исте руте прихватају оба. Тако Zapier и Make могу да региструју вебхукове у име цркве када се Zap или сценарио укључи.

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

Одговор на креирање, и само тај одговор, садржи 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"
}
Метода и путањаСврха
GET /membership/webhooksЛиста вебхукова цркве (тајни кључ није укључен)
GET /membership/webhooks/eventsКаталог важећих назива догађаја
GET /membership/webhooks/:idУчитава један вебхук
POST /membership/webhooksКреира (без id) или ажурира (са id)
POST /membership/webhooks/:id/regenerate-secretМења тајни кључ за потпис; нову вредност враћа једном
DELETE /membership/webhooks/:idБрише вебхук
GET /membership/webhooks/:id/deliveriesНедавни покушаји испоруке за вебхук
GET /membership/webhooks/deliveries/:deliveryIdЦео садржај и одговор за једну испоруку
POST /membership/webhooks/deliveries/:deliveryId/redeliverПоново ставља испоруку у ред

Каталог догађаја​

Називи догађаја прate образац {entity}.{action}. Актуелну листу преузмите са GET /membership/webhooks/events.

ДогађајАктивира се када
person.createdОсоба је додата
person.updatedЗапис о особи је измењен
person.destroyedОсоба је обрисана
household.createdДомаћинство је додато
household.updatedДомаћинство је измењено
household.destroyedДомаћинство је обрисано
group.createdГрупа је додата
group.updatedГрупа је измењена
group.destroyedГрупа је обрисана
group.member.addedОсоба је додата у групу
group.member.removedОсоба је уклоњена из групе
donation.createdПрилог је забележен: ручни унос, онлајн, или прелаз са стања на чекању на завршено
donation.updatedЗапис о прилогу је уређен
attendance.recordedПосета је забележена (ручни унос или пријава)
session.createdНова сесија присуства је креирана (ручно или аутоматски при првој пријави)
form.submission.createdОбразац је послат
event.createdДогађај у календару је додат
event.updatedДогађај у календару је уређен
event.destroyedДогађај у календару је обрисан

Формат садржаја​

Свака испорука је HTTP POST захтев с JSON телом и следећим заглављима:

ЗаглављеОпис
Content-TypeУвек application/json
X-B1-EventНазив догађаја, на пример person.created
X-B1-Delivery-IdЈединствени ИД овог покушаја испоруке. Користите га за уклањање дупликата
X-B1-SignatureHMAC-SHA256 потпис необрађеног тела (видите испод)
X-B1-TimestampUnix време у секундама када је захтев послат
User-AgentB1-Webhooks/1.0

Тело упакује промењени ресурс у мали омотач:

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

За догађаје *.destroyed, data садржи само id и churchId обрисаног записа.

Догађаји чији садржај упућује на друге записе по ИД-у такође садрже читљива имена, која се решавају у време испоруке: personName и groupName за догађаје чланства у групи, personName за догађаје присуства, прилога и чланства на листи, groupName за session.created, и formName (плус personName када је образац повезан са особом) за form.submission.created.

Типови конектора​

Подразумевани формат испоруке је JSON омотач описан горе, connectorType: "standard". За Slack и Discord исти механизам вебхука уместо тога шаље поруку у облику ћаскања коју те услуге директно прихватају:

connectorTypeПослато телоКористите када
"standard" (подразумевано){event, churchId, occurredAt, data} омотач, потписанПишете сопствену интеграцију или се повезујете на Zapier / Make / сопствени сервер
"slack"{ "text": "💝 New donation: $50.00" }Шаљете директно на Slack Incoming Webhook URL
"discord"{ "content": "💝 New donation: $50.00" }Шаљете директно на URL вебхука Discord канала
"mailchimp"није применљиво. Конектор сам позива Mailchimp APIЖелите синхронизацију публике без URL адресе коју треба да хостујете

Тип конектора подешава се у падајућем менију Тип конектора у уређивачу вебхука или преко connectorType у телу захтева POST /membership/webhooks. Потписано заглавље X-B1-Signature се и даље шаље за Slack и Discord испоруке (они га безопасно занемарују), па каснији прелазак вебхука назад на standard не захтева поновно потписивање.

Slack и Discord су чиста промена облика тела. Механизам и даље шаље POST на URL адресу коју је унела црква. mailchimp је први конектор који сам води HTTP размену: за сваки догађај шаље овлашћене захтеве за уметање, архивирање и ознаке ка Mailchimp API-ју (MailchimpConnector.deliver). Његови акредитиви ({apiKey, audienceId}) се чувају шифровани AES алгоритмом у webhooks.connectorConfig, само за упис преко API-ја. Mailchimp вебхукови прихватају само догађаје особа, чланова група и чланова листи. Ruta за чување проверава кључ и публику код Mailchimp-а пре прихватања. Редови испоруке чувају стандардни омотач, па дневник испорука показује шта је B1 видео заједно с одговором Mailchimp-а. Нерасподељене situacije (особа без е-поште, догађај без мапирања) завршавају се као успешне, са телом одговора Skipped:, уместо да троше поновне покушаје.

Тестне испоруке​

Сваки уређивач вебхука има дугме Пошаљи тестовни догађај (Send Test Event). Одговарајући API позив је POST /membership/webhooks/:id/test. Тестна рута прави синтетички садржај за први претплаћени догађај, шаље га синхронизовано кроз стварни путању потписане испоруке (и кроз formatForConnector за Slack и Discord) и враћа добијени ред испоруке, укључујући responseStatus и responseBody. Користите је да потврдите повезаност и руковање потписом пре него што стварно укључите интеграцију. За mailchimp вебхукове тест уместо тога проверава сачуване акредитиве код Mailchimp API-ја (синтетички догађај би у стварну публику цркве уписао лажног претплатника) и враћа резултат у облику испоруке, без креирања реда.

Провера потписа​

Увек проверите X-B1-Signature пре него што верујете садржају. Потпис је sha256= и затим хекс HMAC-SHA256 необрађеног тела захтева, кључан вашим тајним кључем за потпис. Израчунајте га над бајтовима које сте примили. Не серијализујте поново парсирани JSON.

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

Одбаците сваки захтев чији се потпис не поклапа. По жељи, одбаците и захтеве чија је X-B1-Timestamp старија од неколико минута, да бисте ограничили простор за поновно слање (replay).

Подршка за SDK​

За Node.js, @churchapps/integration-sdk испоручује типизовани верификатор и Express middleware који за вас обрађује прихват необрађеног тела, проверу потписа и рашчлањивање омотача:

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 такође нуди WebhookVerifier.verify(secret, rawBody, signatureHeader) за окружења која нису Express (серверлес функције, Fastify и слично). Погледајте пакет на npm-у.

Испорука и поновни покушаји​

Ваша крајња тачка треба што пре да одговори статусом 2xx, идеално тек након што само стави посао у ред, а не након обраде. Сваки одговор који није 2xx, неуспешна веза или одговор спорији од 10 секунди сматра се неуспешном испоруком.

Неуспеле испоруке се понављају уз експоненцијално повећавање интервала: 16 покушаја током отприлике 5 дана. Интервал расте од 1 минута, преко сати, до размака од 3 дана за последње покушаје. Након 16. неуспелог покушаја испорука се означава као exhausted и напушта се.

Испорука је најмање једном (at-least-once): испорука може стићи више пута, на пример ако ваша крајња тачка успе, али одговор буде изгубљен. Користите заглавље X-B1-Delivery-Id за уклањање дупликата. Обрадите сваки ИД само једном, а поновљене испоруке третирајте као без ефекта.

Аутоматско искључивање​

Ако вебхук изазове три узастопне исцрпљене испоруке, B1 га аутоматски искључује. Поправите крајњу тачку, а затим поново укључите вебхук у B1Admin-у (или преко POST /membership/webhooks са "active": true).

Преглед и поновно слање​

Уређивач вебхукова у B1Admin-у приказује табелу Recent Deliveries (Недавне испоруке) са догађајем, статусом, бројем покушаја, кодом одговора и временском ознаком. Избором реда приказује се цео послати садржај и одговор који је стигао.

Користите Redeliver (Поново испоручи) да поново ставите у ред било коју прошлу испоруку с њеним првобитним садржајем. Корисно је након исправке грешке у вашој крајњој тачки или за надокнаду догађаја које је ваша крајња тачка пропустила док није радила.

Захтеви за URL адресу​

Пошто URL адресе вебхукова уноси црква, B1 примењује заштиту од фалсификовања захтева на страни сервера (SSRF). URL адреса вебхука се одбија, и при регистрацији и поново пре сваке испоруке, ако:

  • не користи https
  • упућује на localhost, назив хоста .local или .internal, или
  • се разрешава у приватну, loopback, link-local или cloud-metadata IP адресу

Ваша крајња тачка мора бити јавно доступна HTTPS услуга.