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 webhooks 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 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 App 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 App 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 App 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 namepsace, Costcoder by Smithsoft
would be able 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, App 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 and dashes (-).
- Uppercase letters, numbers, 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 <publisher name>-<application name> 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
rertrieving 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.
Response Attribute | Description | |
---|---|---|
started_at | Start time in UTC for the webhooks event delivery. | |
response_status | Status code returned from the delivery attempt. For example, 200 OK , 404 Not Found , etc. Explanations of common status codes are provided in the RESTful API Concepts guide. |
|
response_headers | Object containing key/value pairs representing the HTTP header fields included in the response to the webhooks delivery POST call. | |
response_error | Error response message, if applicable. | |
response_body | Content of the HTTP response body resulting from the webhooks delivery POST call. | |
outcome | Result for the webhooks event delivery attempt. Can be one of 'ok', 'retried', or 'failed'. | |
id | Unique identifier for the delivery. | |
event_id | Unique identifier for the webhooks event for which a delivery was attempted. | |
event | The event object containing the following properties:
|
|
completed_at | Time in UTC when the webhooks event delivery completed. |
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', or 'failing' webhooks deliveries. Here is the syntax for using the filters[status]
query parameter.
https://api.procore.com/vapid/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', or 'failing'
example: curl -X GET https://api.procore.com/vapid/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.
Metadata Property | Description |
---|---|
source_user_id | The ID of the user from which the change originated. |
source_company_id | The ID of the company from which the change originated. |
source_project_id | The ID of the project from which the change was originated. |
source_application_id | The ID of the application responsible for the change. (Client ID) |
source_operation_id | The ID of the operation responsible for the change. |
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.