Skip to content

Webhooks

Receive Planning Center webhooks: verify signatures, parse typed events, and manage subscriptions.

Updated

Planning Center can POST to your server when data changes (a person is created, a plan is updated, someone checks in). @mackenly/planningcenterkit/webhooks verifies those deliveries and parses them into typed events. It uses WebCrypto and no Node built-ins, so it runs on Node 22+, Bun, Deno, Cloudflare Workers, and Vercel.

How deliveries work

  • You create a subscription per event name (for example people.v2.events.person.created) at api.planningcenteronline.com/webhooks. Each subscription has its own authenticity secret.
  • Each delivery is signed: the X-PCO-Webhooks-Authenticity header is the hex HMAC-SHA256 of the raw request body, keyed with that secret.
  • Respond 200 quickly. Any other status is retried, up to 16 times over about 5 days. A 410 response deactivates the subscription, so never send one by accident.
  • The same event can be delivered more than once; dedupe on event.id if processing it twice would hurt.

Fetch-style handlers (Request / Response)

handleWebhook(request, { secret }) reads the body once, verifies the signature, and returns the parsed events. It works with any standard Request: Cloudflare Workers, Next.js App Router, Bun, Deno, Hono, Remix, SvelteKit, Astro.

import { handleWebhook, isEvent, PcoWebhookError } from '@mackenly/planningcenterkit/webhooks';

export async function onRequest(request: Request): Promise<Response> {
    try {
        const events = await handleWebhook(request, { secret: process.env.PCO_WEBHOOK_SECRET! });
        for (const event of events) {
            if (isEvent(event, 'people.v2.events.person.created')) {
                console.log('new person', event.payload.data.id);
            }
        }
        return new Response('ok');
    } catch (err) {
        // PcoWebhookVerificationError -> 401, PcoWebhookParseError -> 400
        const status = err instanceof PcoWebhookError && 'status' in err ? Number(err.status) : 500;
        return new Response('Rejected', { status });
    }
}

Several subscriptions, several secrets

Each subscription has its own secret. Pass them all, and a delivery is accepted if any matches:

import { handleWebhook } from '@mackenly/planningcenterkit/webhooks';

const events = await handleWebhook(request, {
    secret: [process.env.PCO_PERSON_CREATED_SECRET!, process.env.PCO_PERSON_UPDATED_SECRET!],
});

Or look the secret up by event name. Events you return undefined for are rejected with a 401:

import { handleWebhook } from '@mackenly/planningcenterkit/webhooks';

const secrets: Record<string, string | undefined> = {
    'people.v2.events.person.created': process.env.PCO_PERSON_CREATED_SECRET,
    'people.v2.events.person.destroyed': process.env.PCO_PERSON_DESTROYED_SECRET,
};

const events = await handleWebhook(request, { secret: (eventName) => secrets[eventName] });

The resolver may be async (for example, to read secrets from a database).

Cloudflare Workers

Respond first, then work in ctx.waitUntil():

import { handleWebhook, isEvent, PcoWebhookError } from '@mackenly/planningcenterkit/webhooks';

export default {
    async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
        try {
            const events = await handleWebhook(request, { secret: env.PCO_WEBHOOK_SECRET });
            ctx.waitUntil(Promise.all(events.map(async (event) => {
                if (isEvent(event, 'people.v2.events.person.created')) await onNewPerson(event.payload.data.id);
            })));
            return new Response('ok');
        } catch (err) {
            const status = err instanceof PcoWebhookError && 'status' in err ? Number(err.status) : 500;
            return new Response('Rejected', { status });
        }
    },
};

A complete Worker with per-event secrets and dedupe: examples/cloudflare-worker-webhooks.ts.

Next.js App Router

// app/api/webhooks/pco/route.ts
import { after } from 'next/server';
import { handleWebhook, PcoWebhookParseError, PcoWebhookVerificationError } from '@mackenly/planningcenterkit/webhooks';

export async function POST(request: Request) {
    try {
        const events = await handleWebhook(request, { secret: process.env.PCO_WEBHOOK_SECRET! });
        after(() => processEvents(events)); // respond 200 now, process afterwards
        return new Response(null, { status: 200 });
    } catch (err) {
        if (err instanceof PcoWebhookVerificationError || err instanceof PcoWebhookParseError) {
            return new Response(err.message, { status: err.status });
        }
        throw err;
    }
}

Express and other Node frameworks

Without a Request object, use the two building blocks. The signature covers the exact bytes Planning Center sent, so you need the raw body: express.json() parses and discards it, and JSON.stringify(req.body) won’t reproduce it byte for byte.

import express from 'express';
import { parseWebhook, verifyWebhookSignature } from '@mackenly/planningcenterkit/webhooks';

const app = express();

// Register before any global express.json() so this route keeps the raw Buffer.
app.post('/webhooks/pco', express.raw({ type: 'application/json' }), async (req, res) => {
    const ok = await verifyWebhookSignature({
        body: req.body, // Buffer
        signature: req.get('X-PCO-Webhooks-Authenticity'),
        secret: process.env.PCO_WEBHOOK_SECRET!,
    });
    if (!ok) return res.sendStatus(401);

    const events = parseWebhook(req.body);
    res.sendStatus(200); // acknowledge before slow work
    for (const event of events) await processEvent(event);
});

The same pattern works for Fastify (with a raw-body content type parser), Koa, or plain node:http (collect the chunks into a Buffer).

verifyWebhookSignature returns false (it never throws) for a missing or malformed header, an empty secret, or a mismatch, and compares in constant time. parseWebhook doesn’t verify anything; always verify first.

Events

Each delivery body can hold several events. Each event is:

Property Example Description
id cac783dc-... Delivery id; the same event redelivered keeps it
name people.v2.events.person.updated Full event name
product people Product segment
resource person Resource segment
action updated created, updated, destroyed, or another action
attempt 1 Delivery attempt number
payload { data, included, meta } The changed resource as a JSON:API document (already parsed)
organizationId 127 The organization, when Planning Center included it
raw The raw EventDelivery resource

isEvent() narrows by one name or several, which also narrows product, resource, and action:

import { isEvent, parseWebhook } from '@mackenly/planningcenterkit/webhooks';

declare const rawBody: string;

for (const event of parseWebhook(rawBody)) {
    if (isEvent(event, 'people.v2.events.person.created')) {
        event.action; // 'created'
    } else if (isEvent(event, ['people.v2.events.person.updated', 'people.v2.events.person.destroyed'])) {
        console.log(event.payload.data.id, event.action);
    }
}

The payload is typed as a generic resource, since one endpoint can receive any event. Cast it to the resource type you subscribed to when you need typed attributes:

import type { People } from '@mackenly/planningcenterkit';
import { parseWebhook } from '@mackenly/planningcenterkit/webhooks';

declare const rawBody: string;

const [event] = parseWebhook(rawBody);
const person = event!.payload.data as unknown as People.Person;
console.log(person.attributes.first_name);

parseEventName('people.v2.events.person.created') splits a name into { product, version, resource, action }. The full list of event names is at api.planningcenteronline.com/webhooks/v2/available_events.

Testing your handler

signWebhookBody(body, secret) computes the header Planning Center would send:

import { handleWebhook, signWebhookBody } from '@mackenly/planningcenterkit/webhooks';

const body = JSON.stringify({
    data: [{
        id: 'test-1',
        type: 'EventDelivery',
        attributes: {
            name: 'people.v2.events.person.created',
            attempt: 1,
            payload: JSON.stringify({ data: { type: 'Person', id: '1', attributes: { first_name: 'Ada' } } }),
        },
    }],
});
const request = new Request('http://localhost/webhooks/pco', {
    method: 'POST',
    body,
    headers: { 'X-PCO-Webhooks-Authenticity': await signWebhookBody(body, 'test-secret') },
});
const events = await handleWebhook(request, { secret: 'test-secret' });

Errors

Error status When
PcoWebhookVerificationError 401 Missing header, no secret for the event, or no secret matched
PcoWebhookParseError 400 The body or an event’s payload isn’t valid JSON or isn’t a delivery
PcoWebhookError Base class; thrown directly if the request body was already read

Managing subscriptions

The Webhooks product API lists available events and manages subscriptions:

const events = await pco.webhooks.available_events.toArray();
const subscriptions = await pco.webhooks.webhook_subscriptions.toArray();

await pco.webhooks.webhook_subscriptions.create({
    name: 'people.v2.events.person.created',
    url: 'https://example.com/webhooks/pco',
    active: true,
});

Or, without the rest of the client:

import { createWebhooksClient } from '@mackenly/planningcenterkit/webhooks-api';

const webhooks = createWebhooksClient({ auth: { applicationId: '...', secret: '...' } });
const { data } = await webhooks.webhook_subscriptions.list();

Type to search…

↑↓ navigate↵ selectEsc close