Introduction to Webhooks

Background

The Webhooks feature allows 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. A user interface for configuring the Webhooks feature is available through the Project Admin tab in the Procore Web application.

The benefits of the Webhooks feature include:

  • Improved performance by replacing polling with asynchronous updates
  • Eliminates polling logic/code in third-party integrations to determine resource changes
  • Increased efficiency as code only needs to run when a resource changes
  • Reduced risk of exceeding Procore API Rate Limit caps

How the Webhooks Feature Works

The following diagram illustrates the high-level data flow within the Webhooks system:

Webhooks Data Flow

  • Create, Update, and Delete actions on Procore resources are initiated from client devices. This could include actions initiated from the Procore Web user interface, Procore Mobile, or Procore API calls.
  • If Webhooks are configured on the Company Admin or Project Admin page to monitor these events, then a POST call is made to the connected web service with a JSON payload that contains data identifying the resource that changed.
  • For Creates and Updates, the Resource name and ID contained in the payload from the POST call, the web service can then send a GET request back to the Procore API to gather information about the specified resource that changed.

Payload Definition

Each POST call resulting from an event trigger contains a payload as defined in the following table:

Parameter Description
user_id The ID for the User that initiated the event.
timestamp UTC date/time when the event occurred.
resource_name The name of the Resource in which the event occurred.
resource_id The ID for the Resource in which the event occurred.
project_id The ID of the Project in which the event occurred.
event_type The type of event - will be 'create', 'update', or 'delete'.
company_id The ID of the Company in which the event occurred.
api_version The Procore API version.

An example JSON payload from a CREATE event is shown below:

{ "user_id": 1360281, "timestamp": "2017-03-23T23:02:36Z", "resource_name": "Change Events", "resource_id": 212727, "project_id": 217719, "id": 978654325, "event_type": "create", "company_id": 6449, "api_version": "v2" }

Setting Up Your Web Server

In order to use the Webhooks feature, you will need to set up at least one web server to accept API calls coming from Procore. Your notification endpoint URL must satisfy the following requirements:

  • Must be available on the public Internet.
  • Must support POST calls from Procore carrying the JSON payload described above, parse the JSON, and use that data as needed (e.g., GET call to Procore to show data on a resource).
  • Must correspond to the endpoint URL entered on the Webhooks Configuration page.

The following table describes the content-type, body, and response status codes that your endpoint server must support for the POST call coming from Procore Webhooks:

HTTP Method Content-Type Body Response
POST application/json JSON (see example above) HTTP 200 OK, or HTTP 204 No Content

Monitoring Recommendation

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 visualize 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.

Handling Authorization Header Content

When configuring Webhooks in Procore, you are given the option to define Authorization header information to be sent with all HTTP calls made to your notification endpoint. All Webhooks POST requests delivered by Procore will contain this Authorization information in the request header. The value you enter in the Authorization Header field on the Webhooks configuration page in Procore is used to construct the Authorization header. Though this field can be used to define any authorization header information you wish, it is most commonly used to specify authorization credentials with the following syntax:

Authorization: <type> <credentials>

Note that you only need to enter the value for <type> and <credentials> in the Authorization Header field. The Webhooks feature takes care of prepending the header with Authorization: for you.

Handling Multiple Webhook Deliveries

Webhook deliveries are sent to your system at least once per event. However, it is important to note that your system may occasionally receive a delivery for the same event more than once. We recommend guarding against duplicate event deliveries by designing your event processing system to be idempotent. One approach to handling this scenario is to log each processed event, and then not process previously-logged events.

Webhooks Retry/Backoff Behavior

When a Webhook delivery fails, either because we could not connect to the destination URL, or because the destination returned a non-2XX response code, all future deliveries to that endpoint will be paused. The failing Webhook will then be retried using an exponential backoff scheme, starting with a 1 second interval and with a maximum interval of 1 hour. After 24 hours of retrying event delivery to that destination URL, the delivery queue will be flushed and all queued events will be marked as `failed`. When the next new Webhook to be delivered is ready, it will attempt to delivery it from a fresh start, beginning a new retry cycle if the destination URL remains unavailable. If at any point during the retry cycle a successful delivery occurs, the system will resume sending events as normal and all retry counters will be reset.

Quick Response Recommendation

In order to ensure that you do not receive multiple notifications, it is recommended that your service sends back the 2XX response as soon as possible after receiving the notification, and perform any required processing of the webhook asynchronously. The timeout window on the Procore side is 5 seconds (once a successful connection is established) before the request fails.

Additional Information

Steps for configuring the Webhooks feature in Procore are described in the following articles on our Support Site.