Hoppa till huvudinnehål

Webhooks

Med webhooks kan en kyrka skicka realtidsnotiser till verktyg från tredje part, till exempel automationsplattformar (Zapier, Make, n8n), CRM-system, bokföringssystem eller allt som tar emot en HTTP POST. När en person, grupp eller familj ändras i B1 skickar B1 en signerad JSON-payload till varje URL som prenumererar på händelsen.

Innan du börjar

  • En kyrkadministratör med behörigheten Redigera kyrkoinställningar registrerar och hanterar webhooks
  • Din mottagande endpoint måste vara nåbar via HTTPS på en offentlig adress
  • Ha ett sätt att lagra signeringshemligheten säkert. Den visas bara en gång.

Översikt​

Webhooks är enbart utgående: B1 anropar din endpoint, du anropar inte B1. Varje webhook är en prenumeration per kyrka som består av en måladress (URL), en signeringshemlighet och en lista över prenumererade händelser.

Leveransen använder en varaktig utkorg: När en prenumererad händelse inträffar skapar B1 en leveransrad, och en bakgrundsprocess skickar den med POST inom ungefär en minut. Misslyckade leveranser görs om med exponentiellt ökande väntetid. Inget går förlorat om en leverans är långsam eller din endpoint tillfälligt är nere.

Registrera en webhook​

I B1Admin​

Gå till Inställningar → Utvecklare → Webhooks → Ny webhook. Ange ett namn, payload-URL:en och välj de händelser som du vill prenumerera på. När du sparar visas signeringshemligheten en gång. Kopiera den direkt och lagra den tillsammans med din integration. Den visas aldrig igen. Du kan rotera den senare, men du kan inte hämta den ursprungliga.

Via API:et​

Alla endpoints ligger under sökvägen för Membership-modulen /membership/webhooks och kräver antingen en JWT från en kyrkadministratör med behörigheten Settings / Edit, eller en API-nyckel skapad med scopet settings:write. Samma rutter accepterar båda. Det är det som gör att Zapier och Make kan registrera webhooks för kyrkans räkning när en Zap eller ett scenario aktiveras.

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

Svaret på skapandet, och endast svaret på skapandet, innehåller 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 och sökvägSyfte
GET /membership/webhooksLista kyrkans webhooks (hemligheten utelämnas)
GET /membership/webhooks/eventsKatalogen över giltiga händelsenamn
GET /membership/webhooks/:idHämta en webhook
POST /membership/webhooksSkapa (utan id) eller uppdatera (med id)
POST /membership/webhooks/:id/regenerate-secretRotera signeringshemligheten. Returnerar det nya värdet en gång.
DELETE /membership/webhooks/:idTa bort en webhook
GET /membership/webhooks/:id/deliveriesSenaste leveransförsöken för en webhook
GET /membership/webhooks/deliveries/:deliveryIdFullständig payload och svar för en leverans
POST /membership/webhooks/deliveries/:deliveryId/redeliverLägg tillbaka en leverans i kön

Händelsekatalog​

Händelsenamn följer mönstret {entity}.{action}. Hämta den aktuella listan från GET /membership/webhooks/events.

HändelseUtlöses när
person.createdEn person läggs till
person.updatedEn personpost ändras
person.destroyedEn person tas bort
household.createdEn familj läggs till
household.updatedEn familj ändras
household.destroyedEn familj tas bort
group.createdEn grupp läggs till
group.updatedEn grupp ändras
group.destroyedEn grupp tas bort
group.member.addedEn person läggs till i en grupp
group.member.removedEn person tas bort från en grupp
donation.createdEn gåva registreras: manuell inmatning, online eller övergången från väntande till slutförd
donation.updatedEn gåvopost redigeras
attendance.recordedEtt besök loggas (manuell inmatning eller incheckning)
session.createdEn ny närvarosession skapas (manuellt eller automatiskt vid första incheckningen)
form.submission.createdEtt formulär skickas in
event.createdEn kalenderhändelse läggs till
event.updatedEn kalenderhändelse redigeras
event.destroyedEn kalenderhändelse tas bort

Payloadformat​

Varje leverans är en HTTP-POST med en JSON-body och dessa headers:

HeaderBeskrivning
Content-TypeAlltid application/json
X-B1-EventHändelsenamnet, t.ex. person.created
X-B1-Delivery-IdUnikt id för detta leveransförsök. Använd det för att deduplicera.
X-B1-SignatureHMAC-SHA256-signatur för den råa bodyn (se nedan)
X-B1-TimestampUnix-tid i sekunder när begäran skickades
User-AgentB1-Webhooks/1.0

Bodyn lindar in den ändrade resursen i ett litet kuvert:

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

För händelser av typen *.destroyed innehåller data endast id och churchId för den borttagna posten.

Händelser vars payloads refererar till andra poster via id innehåller också läsbara namn som löses vid leveranstillfället: personName och groupName för gruppmedlemskapshändelserna, personName för närvaro-, gåv- och listmedlemskapshändelser, groupName för session.created och formName (plus personName när inlämningen är kopplad till en person) för form.submission.created.

Anslutningstyper​

Standardformatet för leverans är JSON-kuvertet ovan, connectorType: "standard". För Slack och Discord skickar samma webhook-motor i stället ett chattliknande meddelande som dessa tjänster accepterar direkt:

connectorTypeSkickad bodyAnvänds när
"standard" (standard)Kuvertet {event, churchId, occurredAt, data}, signeratDu skriver en egen integration eller pekar mot Zapier / Make / en egen server
"slack"{ "text": "💝 New donation: $50.00" }Du postar direkt till en Slack Incoming Webhook-URL
"discord"{ "content": "💝 New donation: $50.00" }Du postar direkt till en Discord-kanals webhook-URL
"mailchimp"Ej tillämpligt. Kopplingen anropar Mailchimps API själv.Du vill ha målgruppssynkronisering utan någon URL att hosta

Anslutningstypen väljs i rullgardinsmenyn Connector Type i webhook-redigeraren, eller via connectorType i bodyn för POST /membership/webhooks. Den signerade headern X-B1-Signature skickas fortfarande för Slack- och Discord-leveranser (de ignorerar den utan problem), så det går bra att senare byta tillbaka en webhook till standard utan att signera om något.

Slack och Discord är rena omformningar av bodyn. Motorn skickar fortfarande till den URL som kyrkan angett. mailchimp är den första kopplingen som i stället äger sitt eget HTTP-utbyte. Per händelse gör den autentiserade anrop för upsert, arkivering och taggar mot Mailchimps API (MailchimpConnector.deliver). Dess autentiseringsuppgifter ({apiKey, audienceId}) lagras AES-krypterade i webhooks.connectorConfig och kan bara skrivas via API:et. Mailchimp-webhooks accepterar endast händelser för person, gruppmedlem och listmedlem. Sparrutten verifierar nyckeln och målgruppen mot Mailchimp innan den accepterar dem. Leveransraderna lagrar det standardiserade kuvertet, så leveranslogen visar vad B1 såg tillsammans med Mailchimps svar. Situationer som inte kan mappas (person utan e-postadress, händelse utan mappning) markeras som lyckade med ett svar i bodyn som börjar med Skipped: i stället för att förbruka nya försök.

Testleveranser​

Varje webhook-redigerare har en knapp för Send Test Event. Motsvarande API-anrop är POST /membership/webhooks/:id/test. Testrutten bygger en syntetisk payload för den första prenumererade händelsen, skickar den synkront genom den riktiga signerade leveransvägen (och genom formatForConnector för Slack och Discord) och returnerar den resulterande leveransraden, inklusive responseStatus och responseBody. Använd den för att bekräfta anslutning och signaturhantering innan du slår på integrationen på riktigt. För mailchimp-webhooks verifierar testet i stället de lagrade autentiseringsuppgifterna mot Mailchimps API (en syntetisk händelse skulle skriva en falsk prenumerant till kyrkans riktiga målgrupp) och returnerar ett resultat i leveransformat utan att skapa någon rad.

Verifiera signaturer​

Verifiera alltid X-B1-Signature innan du litar på en payload. Signaturen är sha256= följt av den hexadecimala HMAC-SHA256 för den råa begäran-bodyn, nycklad med din signeringshemlighet. Beräkna den över de byte du tog emot. Serialisera inte om den tolkade JSON:en.

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

Avvisa alla begäranden vars signatur inte stämmer. Du kan också valfritt avvisa begäranden vars X-B1-Timestamp är mer än några minuter gammal, för att begränsa upprepningsfönstret.

SDK-stöd​

För Node.js levererar @churchapps/integration-sdk en typad verifierare och en Express-middleware som sköter insamlingen av den råa bodyn, signaturkontrollen och tolkningen av kuvertet åt dig:

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:t exponerar också WebhookVerifier.verify(secret, rawBody, signatureHeader) för körmiljöer utan Express (serverless-funktioner, Fastify m.fl.). Se paketet på npm.

Leverans och nya försök​

Din endpoint bör svara med status 2xx så snabbt som möjligt, helst efter att bara ha köat arbetet och inte efter att ha bearbetat det. Varje svar som inte är 2xx, ett anslutningsfel eller ett svar som tar längre än 10 sekunder räknas som en misslyckad leverans.

Misslyckade leveranser görs om med exponentiellt ökande väntetid, 16 försök under ungefär 5 dagar. Intervallet växer från 1 minut, via timmar, upp till 3 dygns uppehåll för de sista försöken. Efter det 16:e misslyckade försöket markeras leveransen som exhausted och överges.

Leveransen är minst en gång: en leverans kan komma fram mer än en gång, till exempel om din endpoint lyckas men svaret går förlorat. Använd headern X-B1-Delivery-Id för att deduplicera. Bearbeta varje id bara en gång och behandla upprepningar som no-ops.

Automatisk inaktivering​

Om en webhook ger tre exhausted-leveranser i rad inaktiverar B1 den automatiskt. Åtgärda din endpoint och aktivera sedan webhooken igen i B1Admin (eller via POST /membership/webhooks med "active": true).

Granska och skicka om​

Webhook-redigeraren i B1Admin visar en tabell med Senaste leveranser: händelse, status, antal försök, svarskod och tidsstämpel. Om du väljer en rad visas hela payloaden som skickades och det svar som kom tillbaka.

Använd Skicka om för att lägga tillbaka en tidigare leverans i kön med dess ursprungliga payload. Det är användbart efter att du har åtgärdat ett fel i din endpoint, eller för att efterleverera händelser som din endpoint missade medan den var nere.

Krav på URL:en​

Eftersom webhook-URL:er anges av kyrkan tillämpar B1 skydd mot server-side request forgery. En webhook-URL avvisas, både vid registrering och igen före varje leverans, om den:

  • inte använder https
  • pekar på localhost, ett .local- eller .internal-värdnamn, eller
  • löses till en privat, loopback-, link-local- eller molnmetadata-IP-adress

Din endpoint måste vara en offentligt nåbar HTTPS-tjänst.