Configure Project Webhooks

Last updated
Save as PDF

Objective

Configure the Webhooks feature to receive notifications when one or more Procore API resources change in a project.

Background

The Webhooks feature enables third-party developers and integrators to specify one or more Procore API resources for which they want to be notified when Create, Update or Delete actions occur. The user interface for configuring the Webhooks feature is available through the project's Admin tool in Procore.

The benefits of the Webhooks feature include:

Removing the need for polling logic/code in third-party integrations to determine resource changes
Improved performance by replacing polling with asynchronous updates
Increased efficiency as code only needs to run when a resource changes
Reduced risk of exceeding Procore API rate limit caps

Things to Consider

Required User Permission:
- 'Admin' on the projects's Admin tool.
Developer Information:
- Refer to the Introduction to Webhooks and Using the Webhooks API guides on the Developer Portal for information on developing your application or integration to properly support Webhooks.

Steps

Navigate to the project's Admin tool.
This reveals the 'General Project Information' page.
Under the 'Project Settings' menu in the sidebar, click Webhooks.

This opens the 'Webhooks' configuration page that includes a Notification Endpoint field for entering your web server URL and a Resource Grid for selecting the resources and corresponding change actions for which you want to receive notification.

In the Notification Endpoint field, enter the URL for the endpoint on your web server that will handle the POST requests coming from Procore.
(Optional) In the Authorization Header field, enter the authorisation token that you want to have placed in the header of a POST request coming from Procore. Though this field can be used to define any authorisation header information you wish, it is most commonly used to specify authorisation credentials using the syntax: <type> <credential>, where <type> is the authorisation type ('Basic', 'Token', 'Bearer', etc.) and <credential> is the token value. For example, a valid entry for this field would be Basic c3a24b8208ac5199d083d54a1234e94b8864.
Click Save Endpoint. If you entered a valid, well-formed address in the Notification Endpoint field you will see a green banner appear at the top of the screen indicating success. If there are any problems with the URL you entered, a warning banner will display describing the likely problem.
In the Resource Grid, select the 'Create', 'Update', and 'Delete' actions for any resources you want to receive corresponding notifications. Note that your action selections take effect immediately as you make them, there is no need to 'submit' your changes.

Note: Keep in mind as you configure Webhooks that you are merely identifying which resources/actions you want to receive notifications on. Only when an actual change occurs to a resource will you then receive a notification.

Webhooks Deliveries

A running register of Webhooks Deliveries to your notification endpoint is available at the bottom of the Project Webhooks page. The Deliveries section allows you to quickly see the status of events that Procore has sent (or has attempted to send) to your notification server. Both successful as well as failed deliveries are included in the display by default. You can use the Only Show failures tickbox to filter the display to only show failed deliveries.

The most recent deliveries appear at the top of the Deliveries section. Clicking a delivery entry exposes details on the Request Payload, Response Headers and Response Body.

The display of the deliveries register is paginated with a maximum of 25 deliveries displayed at a time. Clicking More Deliveries will display the next set of 25 deliveries.

Monitoring and Alarms

We strongly recommend that you set up proper monitoring of your notification endpoint servers to ensure that any downtime or other performance-related issues are identified and that you are notified in a timely manner via a reliable alarm system. Many commercial monitoring systems are available that can serve this purpose including Datadog, New Relic and others. These services provide robust monitoring features that allow you to easily visualise the health of your system through configurable charts, graphs and real-time analytics. These services also provide built-in alerting so that you are promptly notified when problems occur.