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.
If you want to implement a feature in your app that currently requires polling our site for information, please contact us about setting up a webhook for the appropriate event.
Notifications
When a webhook is triggered, we will send an HTTP POST request to the target URL that you've registered.
The request will always contain an event query parameter 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 query parameters 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 any 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
Scope:
hooks.manageGrants access to hooks created by other API tokens. This will not be needed for most integrations.