Вебхуки
Вебхуки дають змогу церкві надсилати сповіщення в реальному часі стороннім інструментам: платформам автоматизації (Zapier, Make, n8n), CRM, системам бухгалтерського обліку або будь-чому, що приймає HTTP POST. Коли особа, група чи домогосподарство змінюються в B1, B1 надсилає підписане JSON-корисне навантаження (payload) на кожну URL-адресу, підписану на цю подію.
Перш ніж почати
- Вебхуки реєструє та керує ними адміністратор церкви з дозволом Edit Church Settings
- Ваш кінцевий отримувач має бути доступний через HTTPS за публічною адресою
- Потрібно мати спосіб безпечно зберегти секретний ключ підпису — його показують лише один раз
Огляд
Вебхуки працюють лише вихідно: B1 викликає вашу кінцеву точку, а не навпаки. Кожен вебхук — це підписка для окремої церкви, що складається з URL-адреси призначення, секретного ключа підпису та списку підписаних подій.
Доставка використовує надійну вихідну чергу (outbox): коли відбувається підписана подія, B1 записує рядок доставки, а фоновий процес надсилає POST протягом приблизно хвилини. Невдалі доставки повторюються з експоненційною затримкою. Нічого не втрачається, якщо доставка повільна або ваша кінцева точка тимчасово недоступна.
Реєстрація вебхука
У 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 | Повторно поставити доставку в чергу |
Каталог подій
Назви подій мають шаблон {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-Signature | Підпис HMAC-SHA256 необробленого тіла (див. нижче) |
X-B1-Timestamp | Час надсилання запиту в секундах Unix epoch |
User-Agent | B1-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" } | Ви надсилаєте безпосередньо на URL вхідного вебхука Slack |
"discord" | { "content": "💝 New donation: $50.00" } | Ви надсилаєте безпосередньо на URL вебхука каналу Discord |
"mailchimp" | Не застосовується — з'єднувач сам викликає API Mailchimp | Ви хочете синхронізацію аудиторії без URL-адреси для розміщення |
Тип з'єднувача встановлюють у випадаючому списку Connector Type в редакторі вебхука або через connectorType у тілі POST /membership/webhooks. Підписаний заголовок X-B1-Signature усе одно надсилається для доставок у Slack і Discord (вони його просто ігнорують), тому пізніше перемкнути вебхук назад на standard можна без повторного підписування.
Slack і Discord лише змінюють форму тіла — механізм усе одно надсилає POST на URL, наданий церквою. mailchimp — перший з'єднувач, який сам керує HTTP-обміном: для кожної події він виконує автентифіковані запити upsert/archive/tag до API Mailchimp (MailchimpConnector.deliver), а його облікові дані ({apiKey, audienceId}) зберігаються в webhooks.connectorConfig у шифруванні AES і доступні лише для запису через API. Вебхуки Mailchimp приймають лише події особи, членства в групі та членства у списку; маршрут збереження перевіряє ключ і аудиторію в Mailchimp перед прийняттям. Рядки доставки зберігають стандартний конверт, тож журнал доставки показує, що бачила B1, разом із відповіддю Mailchimp. Ситуації, для яких немає відповідності (особа без електронної пошти, подія без зіставлення), позначаються як успішні з текстом відповіді Skipped: і не витрачають спроби повтору.
Тестові доставки
Кожен редактор вебхука має кнопку Send Test Event (Надіслати тестову подію) — відповідний виклик API: POST /membership/webhooks/:id/test. Тестовий маршрут створює синтетичне корисне навантаження для першої підписаної події, синхронно надсилає його справжнім шляхом підписаної доставки (а для Slack/Discord — через formatForConnector) і повертає отриманий рядок доставки, включно з responseStatus і responseBody. Використовуйте його, щоб перевірити з'єднання та обробку підпису, перш ніж вмикати інтеграцію для реальних даних. Для вебхуків mailchimp тест натомість перевіряє збережені облікові дані через API Mailchimp (синтетична подія записала б фальшивого передплатника в реальну аудиторію церкви) і повертає результат у форматі доставки без створення рядка.
Перевірка підписів
Завжди перевіряйте 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 містить типізований верифікатор і проміжний обробник (middleware) для Express, який бере на себе захоплення необробленого тіла, перевірку підпису та розбір конверта:
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 показує таблицю Останні доставки — подія, статус, кількість спроб, код відповіді та час. Вибір рядка показує повне надіслане корисне навантаження та отриману відповідь.
Скористайтеся Redeliver (Повторно надіслати), щоб повторно поставити в чергу будь-яку минулу доставку з її початковим корисним навантаженням — це корисно після виправлення помилки у вашій кінцевій точці або щоб надолужити події, які вона пропустила, поки була недоступна.
Вимоги до URL-адреси
Оскільки URL-адреси вебхуків надає церква, B1 застосовує захист від підробки запитів на боці сервера (SSRF). URL-адресу вебхука буде відхилено — під час реєстрації та знову перед кожною доставкою — якщо вона:
- не використовує
https - вказує на
localhost, ім'я хоста.local/.internal, або - розв'язується в приватну, loopback, link-local або IP-адресу метаданих хмари
Ваша кінцева точка має бути публічно доступною службою HTTPS.