Перейти до основного вмісту

Вебхуки

Вебхуки дають змогу церкві надсилати сповіщення в реальному часі стороннім інструментам: платформам автоматизації (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-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" }Ви надсилаєте безпосередньо на 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.