Introduction to Webhooks

Background

A webhook is an automated message, or an HTTP request, sent from one application to another in real-time when a specific event occurs, allowing for real-time data updates without the need for constant polling or manual requests. Webhooks automate the process of transferring data between applications, eliminating the need for one application to constantly check for updates from another. In the context of Procore, the Webhooks feature allows company and project administrators to enable third-party developers and integrators to subscribe to event notifications for one or more Procore API resources when Create, Update, or Delete actions occurg. For example, a third-party RFI integration may want to be notified whenever a new RFI is created in Procore.

The benefits of the Webhooks feature include:

• Enabling instant communication between Procore and third-party applications and services. Instead of waiting for an application to request information, webhooks push data from Procore as soon as an event occurs. This ensures that systems are always up-to-date.
• Enabling the automation of workflows by triggering actions in third-party applications whenever specific events take place.
• By eliminating the need for constant polling, webhooks reduce the load on servers and conserve bandwidth. This results in more efficient use of resources.
• Reducing the number of API requests through polling can lead to significant cost savings, especially for applications that handle large volumes of data.

How the Webhooks Feature Works

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

• 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 web service containing an event object as part of the JSON payload. The event object identifies the resource that changed, the type of change, a timestamp, etc.
• For Creates and Updates, the Resource name and ID are contained in the event object. The web service can then send a GET request back to the Procore API to gather information about the specified resource that changed.

Using a Developer Managed Service Account (DMSA) with the Webhooks Feature

We recommend using a Developer Managed Service Account (DMSA) for authenticating GET requests back to the Procore API when gathering information about resources that have changed. DMSAs are the preferred authentication method for data connection applications and allow you to specify the exact company and project level tool permissions that are required for your application to run properly on the Procore platform. Using a DMSA alleviates the scenario where an individual user authenticating through the authorization code grant type may not have adequate permissions to retrieve information for a changed resource. See Developer Managed Service Accounts for additional information.

Webhook Payload Definition

An webhook payload generated by a resource change contains the following properties. This table lists properties for the existing legacy Webhooks payload format. For more information on other supported payload formats, see Webhooks Payload Formats.

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

{
  "api_version": "v2",
  "company_id": 6452,
  "event_type": "create",
  "id": 5982324300946918154,
  "metadata": {
        "source_application_id": null,
        "source_company_id": 6452,
        "source_operation_id": null,
        "source_project_id": 219542,
        "source_user_id": 1469242
  },
  "project_id": 219542,
  "resource_id": 245510722,
  "resource_name": "Purchase Order Contract Line Items",
  "timestamp": "2020-07-20T15:22:01.353581Z",
  "ulid": "01EDPD2J6SBY1163N77H95GW09",
  "user_id": 1469242
}

PAYLOAD DELIVERIES

Note that payloads are bundled into one or more Webhooks deliveries sent to your web service. The delivery contains additional fields and contextual information about the events. For details regarding Webhooks deliveries, please refer to Using the Webhooks API.

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:

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.

MULTIPLE WEBHOOK EVENTS FOR A SINGLE USER ACTION

There are a number of circumstances that can delay an event in the pipeline from Procore’s databases to a Webhook delivery. Logs may show two events having the same timestamp (and thus part of the same database transaction), but distinct IDs indicating they are two separate events in the pipeline. Although the Procore Webhooks feature attempts to account for such delayed events before initiating a Webhook delivery, there may be times when duplicate events reach your Webhooks delivery endpoint. Your system must be properly architected to handle these scenarios. This Wikipedia article covering the Two Generals Problem may provide some deeper insight and guidance into how you might address this issue when designing your system.

Webhooks Retry/Backoff Behavior

When a Webhook delivery fails, due to a failure to establish a connection to the destination URL, the destination returning a non-2XX response code, or the request timing out (5 seconds), 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 12 hours of retrying event delivery to that destination URL, the delivery queue will be flushed and all queued events will be marked as discarded. When the next new Webhook to be delivered is ready, it will attempt to deliver 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.

• Configure Company Webhooks
• Configure Project Webhooks