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
contacts.read scope can register to receive
notifications about address updates.
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
No Content response to indicate that you've successfully
received the notification, but 200-series status will be accepted.
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.
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_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.
- Grants access to hooks created by other API tokens. This will not be needed for most applications.
- 403 hooks.access_denied
- Your API token is attempting to access a webhook that it didn't create, without the
- 404 hooks.not_found
- The specified webhook doesn't exist.