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 Company Admin and Project Admin tabs 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:

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

Event Object Definition

An event object generated by a resource change contains the following properties:

An example event object 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
}

WEBHOOKS DELIVERY PAYLOADS

Note that event objects are bundled into one or more Webhooks deliveries sent to your web service. The delivery payload contains additional fields and contextual information about the event. 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