Introduction to Webhooks


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:

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

Event Object Definition

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

Event Property Description
api_version Procore API version.
company_id ID of the Company in which the event occurred.
event_type Type of event - 'create', 'update', or 'delete'.
id ID of the event.
metadata An object containing contextual information about the event.
project_id ID of the Project in which the event occurred.
resource_id ID for the Resource in which the event occurred.
resource_name Name of the Resource in which the event occurred.
timestamp UTC date/time when the event occurred.
ulid Unique identifier encoded as a 26 character string. Populated with a universally unique lexicographically-sortable identifier. See ULID specification for additional information.
user_id ID of the User that initiated the event.

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

{ "api_version": "v2", "company_id": 6452, "event_type": "create", "id": 11301387632, "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": "Images", "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:

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.

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