Webhooks API

Would you like your app to be notified when things happen at prayerletters.com? Webhooks let you subscribe to the events that interest you, and we'll notify you when they happen. This eliminates the need for polling, and provides your app (and therefore your app's users) with real-time updates.

Webhooks can be created by any API token that would otherwise have access to poll for the same information. For instance, an API token with contacts.read scope can register to receive notifications about address updates.

Notifications

When a webhook is triggered, we will send an HTTP POST request to the target URL that you've registered.

There will always be an event parameter added to the URL containing the event that triggered the webhook. Typically, each request will also contain a JSON body with more information, as well as a small set of parameters in the URL that will provide context in case your app isn't able to read the body of the request.

Your application should return a 200 OK or 204 No Content response to indicate that you've successfully received the notification, but 200-series status will be accepted.

Retries

If your app isn't available or returns an error when a webhook is triggered, we will retry at increasing intervals for up to a week. Note that this can lead to notifications coming in out of order.

Handling Loops

Some integrations will have API calls that trigger webhook events. For example, an app that manages a mailing list sends address updates via the API, which will trigger a the address update webhook.

In these cases, there will be a loopback_token and/or loopback_client parameter in the URL indicating that the event was triggered by the same token or client, respectively. If the webhook has a JSON body, there will also be a field with the same name and a true value at the top level of the object.

You can use these two fields to filter out activity that you initiated, or to verify that it has happened.

Permissions

hooks.manage

Grants access to hooks created by other API tokens. This will not be needed for most applications.

Common Errors

403 hooks.access_denied

Your API token is attempting to access a webhook that it didn't create, without the hooks.manage scope.

404 hooks.not_found

The specified webhook doesn't exist.