This one is for the programmers and the teams who build on top of the Planning Center API. We're excited to introduce webhooks! Webhooks give your website or application a way to receive updates from Planning Center in real time, without having to continuously poll the API and hunt for changes. Read the documentation.

Webhook

Starting With Planning Center People

In this initial release, we're starting small and focusing on Planning Center People. Besides, that's where most people's integration journey starts anyway. As time goes on, we'll start adding more hooks for other Planning Center applications.

Webhooks 101

Let's say I'm building an application, and I want to keep my member database up to date with Planning Center People, the central people database for all of Planning Center. Oh, and I want to make sure basic contact data is up to date, too. So, I want to be updated whenever someone is added, when someone is removed, or their email address or phone numbers change.

I first head over to https://api.planningcenteronline.com, log in, and then head to the new Webhooks tab:

Webhooks

Time to set up a new subscription for my application! I could set up a single endpoint for all my webhook subscriptions (like https://myapplication.com/planning-center-integration), but I'm going to be a bit more organized. I'll set up a specific URL for people updates like this: https://myapplication.com/planning-center-integration/person-update) and subscribe it to all the relevant webhooks.

Webhooks

Upon review, I can see that my URL is up and running, and all the subscriptions are active:

Webhooks

If I click on one the people.v2.events.person.created subscription, it looks like someone was just added to Planning Center People!

Webhooks

Clicking "Delivery" let's me review the request and the response from my own application server. Here's the data object:

JSON data

Well, hello Gene! My application has received that JSON payload just seconds after Gene was added to Planning Center. My application can now take that data and, in this case, create Gene's person record on my end. I can also use the links object to initiate other API calls related to our new member.

The Gritty Details

We took a look at the webhook systems we like using, stole some ideas, and came up with some of our own:

  • The webhook API is largely self-documenting.
  • It's built on the back of the existing REST API.
  • There's an interface for inspecting requests and responses.
  • You can initiate manual redeliveries for easier debugging.
  • There are no rate limits.

The system is also built to handle brief outtages on your end. Undelivered webhooks will automatically retry up to 16 times with an exponential backoff. You'll receive an email after it's failed for an hour and another email after the final try (over 5 days after the first failure). After that, the webhook subscription is automatically deactivated. It can be easily reactivated once you've located your server administrator who has been deep in the Brazilian jungle on a journey of self discovery 🏕.

Dive In!

Please drop by the #api channel in the Planning Center Slack Community and let us know what you think and which types of webhooks you'd like to see. As always, you can let us know if you encounter any issues in Github. And if you've never gotten started with developing on our API, check out developer page to get started.

Your fellow developers,
~ Planning Center