Webhooks

A webhook is a configured action (an HTTP POST call to an external URL in this case) executed in response to one or more events in HacknPlan at a project level. This is a way of keeping other systems (tools, services, integrations) in sync by notifying them when something has changed.

Managing webhooks

You can create and manage webhooks from the Administration -> Webhooks section of your project, or using the Public API endpoint.

A webhook basically consists of 3 elements:

• A URL that will be called using POST, including a JSON body with the data (depending on the event).
• A list of events the webhook is subscribed to. The full list of events can be retrieved using an API endpoint. The event that triggered the call will be included in a header called “X-HacknPlan-Event”.
• (Optional) A list of headers that will be included in the request. This is useful in order to include authentication, authorization or other headers necessary to make the call work properly. The header string should have the format {name}: {value}.

Webhooks can be edited, disabled and removed from the Administration -> Webhooks section of the project.

Webhook activity and retry policy

You can take a look at the recent webhook activity by clicking on the webhook entry at Administration -> Webhooks. It will display a list of the webhook calls in the last 30 days, including the event which triggered it, their current status and the attempts made.

You can also expand the calls to get more information about them, like the request body sent or a list of the attempts made with their response times and HTTP response codes and messages.

When a webhook fails, it is automatically retried up to 5 times, the first one hour after the initial attempt, and the rest once per day at the same time that the original event. If all the automated attempts fail, the call will be left as failed and the admins of the project will be notified.

When a webhook has less than a 20% success rate in the last 7 days with a threshold of at least 20 calls, it is automatically disabled and the admins of the project are notified accordingly.