Using the Webhooks API

Overview

In addition to using the Procore Web user interface for configuring Webhooks, you can accomplish this task programmatically using the Webhooks API endpoints. Managing Webhooks using the API involves creating and manipulating Hooks and Triggers. A Hook represents the relationship between a Company/Project and the Notification Endpoint you want to send webhook events to. Triggers belong to a Hook and represent Procore resources that will trigger webhook notifications when those resources are created, updated, or deleted (specified by the Trigger’s Event Type).

The Webhooks API endpoints allow you to configure Webhooks programmatically as well as examine webhook deliveries. These endpoints are documented in the following reference pages:

• Webhooks Hooks - Create, List, Update, Delete
• Webhooks Triggers - Create, List, Delete
• Webhooks Deliveries - List

Webhooks Configuration Using the API

The first step in configuring Webhooks through the API is to create one or more Hooks using the Create Webhooks Hook endpoint. This endpoint provides individual body parameters for specifying the company (company_id) or project (project_id). If you are configuring company-level Webhooks, then you only need to include the company_id parameter in your request body. Similarly, if you are configuring project-level Webhooks then you only need to specify the project_id parameter.

Here is an example request body for creating a Webhooks Hook at the company level:

{
  "company_id":5358233,
  "hook":{
    "api_version":"v2",
    "namespace":"procore",
    "destination_url":"http://webhooks.mydomain.com",
    "destination_headers":{
      "Authorization":"Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzUxMiJ9"
    }
  }
}

In the example above we are creating a Hook for the company associated with "company_id":5358233. In the hook object we specify “v2” for the api_version attribute, “procore” for the namespace attribute (see additional information on namespaces below), we use the destination_url attribute to define the URL for the Notification Endpoint, and the destination_headers attribute to include an Authorization Header.

If we compare the example request body to what we see on the Company Webhooks page in the Procore Web user interface, we find that attributes of the hook object are exposed in the Endpoint Configuration section. See Configure Company Webhooks for additional information.

To create a project-level Hook you would simply use the project_id parameter rather than the company_id parameter. See Configure Project Webhooks for additional information.

Once you have created a Hook (at either the company or project level), you can add one or more triggers to that Hook using the Create Webhooks Trigger endpoint. This endpoint requires the target_id as a path parameter and the api_version as a request body parameter. In addition, the trigger object is required in the request body with resource_name and event_type attributes.

Here is an example request body for creating a Webhooks Trigger at the company level:

{
  "company_id":5358233,
  "api_version":"v2",
  "trigger":{
    "resource_name":"Company Users",
    "event_type":"update"
  }
}

In this example, we are creating a Trigger for the update action on the Company Users resource in "company_id":5358233.

If we compare the example request body to what we see on the Company Webhooks page in the Procore Web user interface, we find that the attributes of the trigger object are exposed in the Webhooks Configuration section. See Configure Company Webhooks for additional information.

Downloadable Resource Name File

Due to the large number of resources accessible through the Procore API, it can be challenging to identify the correct resource names to use when configuring Webhooks Triggers. To help simplify this task, we provide a downloadable CSV file that lists the currently available resources grouped by product category and tool. Using this file, you can directly retrieve the available resource names you need without having to visit the Webhooks Configuration page in Procore to view the large resource list displayed there. It is important to note that the number of Procore resources accessible through the API is growing constantly. As a result, the contents of the CSV file available here may not always accurately reflect the total number of resources currently available to you for configuring Webhooks. Keep in mind that the contents of the CSV file are subject to change and we will strive to update this file on a regular basis. If you need assistance discovering resource names or working with the CSV file, please contact our API support team at apisupport@procore.com.

Common Webhooks API Use Cases

There are a number of common use cases that the Webhooks API is designed to support. These use cases range from single-administrator, single-company Webhook configuration to more complex multi-company scenarios. The most popular Webhooks API use case scenarios are described in the following sections.

Single Company Account Scenario

The most basic use case for the Webhooks API supports Procore client administrators who want to perform Webhook configuration in their company account programmatically rather than through the Procore Web user interface. Some Procore administrators will find it more convenient to use the Webhooks API, especially when they need to configure Webhooks for a large number of projects. The following illustration depicts this scenario.

In the example above, the Procore administrator for Company A is executing Webhooks API calls to configure company-level and project-level Webhooks within the Company A Procore account.

Multiple Company Account Scenario

Many Procore clients leverage one or more Procore Marketplace integrations provided by Procore Technology Partners or utilize custom integrations developed by third-party integrators. Under this scenario, Procore Technology Partners and third-party integrators must design their integrations to allow multiple Hooks to exist for the same Company/Project, and to ensure that each Hook can only belong to a single Company/Project. The Webhooks API provides the namespace feature to support this requirement. When the namespace parameter is included in a Webhooks Hook API call, it ensures that the changes resulting from that call are isolated from changes initiated via a call under a different namespace. Procore Technology Partners and third-party integrators therefore define a unique namespace for each application/integration they develop. See Namespace Best Practices below for additional information.

Namespaces allow for more than one Marketplace integration to interact with a given company account so that one integration can independently perform CRUD operations on Hooks and Triggers without affecting operations performed by another integration. Procore Technology Partners should use a single, unique namespace per app/integration across all Companies/Projects that utilize their integration. The use of namespaces is depicted in the following illustration.

This diagram above shows two Procore Marketplace Applications and a single system integrator interacting with two separate companies running Procore. Each entity has an associated namespace with which Webhooks API CRUD operations are called. The Costcoder application published by Smithsoft is making Webhooks API calls into Company A and Company B using the namespace smithsoft-costcoder. By using this unique namespace, Costcoder by Smithsoft would be able to find their Webhook Hooks for Company A (company_id=1234) by using the List Webhook Hooks call with namespace=smithsoft-costcoder and company_id=1234. The diagram also shows the Bidquick application published by Devpro making Webhooks API calls into Company A and Company B using the namespace devpro-bidquick. Note that both the Costcoder and Bidquick applications are able to manage Webhooks in Project 1 in Company B via the API because they use unique namespaces. Finally, ACME Integrators is working exclusively for Company B and has defined namespace acme-integrators for their use.

Namespace Requirements and Best Practices

As described in the previous section, Marketplace applications and system integrators use namespaces to isolate their Webhooks API calls from one another. When using the namespace parameter, there are a number of requirements and best practices to be considered:

• Namespaces are string values restricted to lowercase a-z, digits 0-9, and dashes (-).
• Uppercase letters and special characters are not supported in namespaces.
• If no namespace is provided with a call, the default “procore” namespace is assumed.
• We recommend the format - for defining namespaces.

Webhooks Deliveries

You can use the List Webhooks Deliveries API endpoint to return a list of the current webhooks events that Procore has delivered (or has attempted to deliver) to your notification server. This provides a convenient alternative to the Procore Web user interface for retrieving information about webhooks event deliveries. Include the hook_id path parameter to specify the webhooks hook you want to see deliveries for. Use the project_id or company_id query parameter to indicate whether you want to return project or company webhooks deliveries respectively. You can also use the filter[status] query parameter to specify whether you want to retrieve ‘any’ (all), ‘successful’, or ‘failing’ deliveries.

The following table describes the various attributes of the List Webhooks Deliveries response body.

Filtering the List Webhooks Deliveries Response

Due to the potential large volume of webhooks deliveries your system might be required to consume, you may find it helpful to filter the response from the List Webhooks Deliveries call using the filters[status] query parameter. This query parameter lets you limit the response to ‘any’ (default), ‘successful’, ‘discarded’, or ‘failing’ webhooks deliveries. Here is the syntax for using the filters[status] query parameter.

https://api.procore.com/rest/v1.0/webhooks/hooks/<HOOK_ID>/deliveries?company_id=<COMPANY_ID>&filter[status]=<FILTER_VALUE>

where:  <HOOK_ID> is the ID for webhook hook
        <COMPANY_ID> is the ID for company (could also be <PROJECT_ID>)
        <FILTER_VALUE> is the filter setting - either 'any', successful', 'discarded', or 'failing'

example:  curl -H "Authorization: Bearer <ACCESS_TOKEN>” -H "Procore-Company-Id: 987654" 
                -X GET https://api.procore.com/rest/v1.0/webhooks/hooks/12345/deliveries?
                company_id=987654&filter[status]=failing

Using Event Metadata to Refine Webhook Delivery Handling

There may be cases where you need to further refine your handling of Webhooks deliveries. For example, if your integration tracks changes in a project but also makes its own changes, you may want to ignore the Webhook deliveries for the changes your integration makes itself. The payload of each Webhook delivery includes a metadata object with properties that provide information about the context of the event. You can use these properties to help you tailor your handling of Webhook deliveries. The following table describes the various properties of the metadata object.

NULL VALUES IN WEBHOOKS METADATA

You may notice that the metadata source_company_id, source_project_id, and source_user_id values return as null within the metadata object. Because this data should already be present within the webhooks payload (simply as company_id, project_id, and user_id, respectively), those fields will occasionally be nullified by our system.

These properties can be used to refine how your integration handles certain Webhooks deliveries. For example, you can use the source_user_id property to ignore events generated by a certain user. This could be useful for service account integrations that want to exclude processing events originating from the service account user. The source_company_id and source_project_id properties can be used to identify events originating from a particular company or project respectively. Events initiated by a particular application can be tracked using the source_application_id property.