You are here

Working with Webhooks

Submitted by Autumn on March 14, 2013 - 5:07pm

This post deals with NationBuilder and assumes you have some knowledge of HTTP POST requests and PHP.

Webhooks offer developers a simple way to record NationBuilder data outside of NationBuilder. You can set up webhooks by visiting the admin dashboard of your Nation, going to "Settings", and then selecting "Webhooks." You should see a page that gives you the following form fields: When to POST, URL to POST to, and below those, you'll see a list of the webhooks that have already been created (if there are any).

The first thing you'll want to do is test to see what kind of data NationBuilder is going to output. You can do this with a free third-party service called RequestBin. To create a new bin, just click on "Create a RequestBin." At the top (in the black bar), you should see a URL similar to this one: http://requestb.in/qfu96wqf. That's the URL you'll want to paste into the "URL to POST to" field back in your NationBuilder new webhook form. Once you've done that, click "Add webhook." Your new webhook should appear at the bottom of the "Current web hooks" list.

Now that you've created your webhook to test the data it will output, click "Send a random test payload" next to your new webhook. If you switch back to your RequestBin URL (e.g. http://requestb.in/qfu96wqf?inspect) and reload the page, you should see the data output. It is recommended that you paste this into a text editor (e.g. JSONLint) to format it for easier reading, like I've done below. This is the data that was sent using the "Person changed" webhook. (I've also omitted a chunk of the data for brevity.)

  1. {
  2.     "payload": {
  3.         "signup": {
  4.             "assistant_email": null,
  5.             "assistant_first_name": null,
  6.             "assistant_last_name": null,
  7.             [...]
  8.             "unsubscribed_at": null,
  9.             "website": null,
  10.             "work_phone_number": null
  11.         }
  12.     },
  13.     "token": null
  14. }

So now that we have this data, what can we do with it? Let's say you want to backup your data in your own database outside of NationBuilder without having to export your lists manually. You could set up a script to add/update data every time a person is changed, which includes those times when a new person is created. Below is an example of how that script would be set up using PHP.

[gist:5165395]

Of course, this is just one of many useful things you can do with webhooks in NationBuilder. And while there is currently no way to push data back to NationBuilder, the ability to back up that data can give you peace of mind that you will never lose that valuable supporter data.

Many thanks to Marjorie Roswell of Baltimore Urban Agriculture for her assistance!