Webhooks are a subscription service, allowing a consumer to receive automatic parcels of data when certain events occur.
Webhooks are used to receive data as it happens, compared to polling an API (calling an API at regular intervals) to see if new or changed data are available. With webhooks, you only need to create the webhook a single time and the subscription will do the rest of the delivery work for you.
Webhooks are used in a wide range of scenarios, including:
- Sending notifications about events on ProductPlan to collaboration platforms. For example, sending a notification to Slack when there's a change to a bar.
- Updating an external issue tracker like Jira.
- Logging events as they happen on Product Plan, for audit purposes.
When you create a webhook, you set up a destination and subscribe to your chosen events that happen within ProductPlan. If your server is set up to “listen” for these webhooks, it can take additional action when those webhooks are received.
Headers
To ensure that the requests you're getting at your webhook endpoint are actually coming from ProductPlan, ProductPlan populates a X-PRODUCTPLAN-WEBHOOK-TOKEN header if the webhook is configured with a token.
Payloads
All payloads will follow the following structure, providing information about the actor performing the action with the name and email, the date and time the Webhook was sent, the event that took place, and all the data associated with it.
{
"actor": {
"name": "name",
"email": "[email protected]"
},
"webhook_created": "YYYY-MM-DD HH:MM:SS UTC",
"event": "{action (ie. bar_create)}",
"data": []
}