Set Up Webhooks

Quick start to creating hooks, adding triggers, and monitoring deliveries.

Overview

New to webhooks? This page is the implementation guide — a quick start for setting up hooks, triggers, and deliveries via the API. For background concepts, event payloads, and how delivery works, see How Webhooks Work.

Use the Webhooks API to programmatically create and manage webhook configuration in Procore. You’ll create a hook (the endpoint + scope) and then add one or more triggers (the resources and events you care about). Finally, you can review recent deliveries for troubleshooting.

To receive project events, choose between listening to every project with one Company Level hook, or to specific projects with Project Level hooks. See Choose Your Scope.

This guide is a quick start with light best practices. It intentionally avoids UI comparisons and deep background so you can set things up fast.


Things to Consider

  • You have API access and a valid access token.
  • Decide your scope: a Company Level hook, or a Project Level hook. See Choose Your Scope.
  • Your notification endpoint accepts HTTPS POST requests and returns a 2xx status when it successfully receives an event.
  • Plan to handle retries and duplicate deliveries (design idempotent processing).

Endpoints


Choose Your Scope

A hook is created at the Company Level or the Project Level, and that decides which events it can receive.

You want to receive Create Use
Project events for all current and future projects One Company Level hook, with triggers on project resources Company Webhooks API and tool
Project events for specific projects only A Project Level hook on each project Project Webhooks API and tool
Company Level events, such as Company Users A Company Level hook Company Webhooks API and tool

A Company Level hook with project resources subscribes once for every project in the company, including projects created later, with no per-project setup. Each event carries the project_id of the project where it occurred.

Choose Project Level hooks when you want events from only some projects. Project Level hooks are created per project, so a project you haven’t set up sends nothing.

Find the resources you can subscribe to. List a company’s webhook resources with include_project_resources=true to return project resources after the company ones. Each resource has a scope of company or project.

curl -H "Authorization: Bearer <ACCESS_TOKEN>" -H "Procore-Company-Id: 987654" \
  "https://api.procore.com/rest/v2.0/companies/987654/webhooks/resources?payload_version=v4.0&include_project_resources=true&all=true"




1. Create a Hook

Keep destination_headers minimal and do not log secrets. Rotate tokens periodically.

Create a hook at the scope you chose. payload_version, namespace, and destination_url are required. New integrations should use v4.0. See Payload Formats.

Example — Company Level hook (company events, or project events for all projects)

POST /rest/v2.0/companies/{company_id}/webhooks/hooks

{
  "payload_version": "v4.0",
  "namespace": "your-integration-name",
  "destination_url": "https://webhooks.yourdomain.com/events",
  "destination_headers": {
    "Authorization": "Bearer <token>"
  }
}

Example — Project Level hook (one specific project)

POST /rest/v2.0/companies/{company_id}/projects/{project_id}/webhooks/hooks

{
  "payload_version": "v4.0",
  "namespace": "your-integration-name",
  "destination_url": "https://webhooks.yourdomain.com/events",
  "destination_headers": {
    "Authorization": "Bearer <token>"
  }
}

2. Add Triggers

Triggers define which resource events should generate webhooks.

Endpoint: POST /rest/v2.0/companies/{company_id}/webhooks/hooks/{hook_id}/triggers for a Company Level hook, or POST /rest/v2.0/companies/{company_id}/projects/{project_id}/webhooks/hooks/{hook_id}/triggers for a Project Level hook.

Body must include resource_name and event_type (create, update, or delete).

Example — add a trigger for all projects. On a Company Level hook, choose a resource whose scope is project:

{
  "resource_name": "RFIs",
  "event_type": "create"
}

Example — add a Company Level trigger

{
  "resource_name": "Company Users",
  "event_type": "update"
}

Finding resource names

  • Use the Webhook Resources list, as in Choose Your Scope, to look up valid resource_name values and the actions each supports.
  • Only add the triggers you need to reduce noise and processing.


3. Monitor Deliveries

Use deliveries to see what Procore sent to your endpoint and how your endpoint responded.

Endpoint: GET /rest/v2.0/companies/{company_id}/webhooks/hooks/{hook_id}/deliveries, or GET /rest/v2.0/companies/{company_id}/projects/{project_id}/webhooks/hooks/{hook_id}/deliveries for a Project Level hook.

Query parameters

  • filter[status] — succeeded, failed, discarded, enqueued, or retrying

Example — list failed deliveries

curl -H "Authorization: Bearer <ACCESS_TOKEN>" -H "Procore-Company-Id: 987654" \
  "https://api.procore.com/rest/v2.0/companies/987654/webhooks/hooks/12345/deliveries?filter[status]=failed"

Useful delivery fields

  • status: the delivery’s current state, such as delivered, failed, discarded, enqueued, or retrying
  • payload: the event your endpoint received, including id, timestamp, resource_name, resource_id, event_type, company_id, project_id, and api_version
  • delivery_attempts: one entry per attempt, each with success, response_status, response_headers, response_body, started_at, and completed_at


Best Practices

  • Start small: enable webhooks in a sandbox, then one project/company before scaling. A Company Level hook with project resources reaches every project, so test it in a sandbox first.
  • Return fast: respond 2xx quickly and process work asynchronously to avoid timeouts.
  • Be idempotent: dedupe/retry safely using the event id (or ULID) and your own keys.
  • Filter your own changes: use event metadata (e.g., source_user_id or source_application_id) to avoid loops from your integration.
  • Secure the endpoint: HTTPS only, rotate secrets, and verify the Authorization header.
  • Log and alert: monitor failing deliveries and error spikes.
  • Limit triggers: subscribe only to resources/events you actually need.

Namespaces (Required)

Namespaces isolate your app’s hooks and triggers from others.

  • Allowed characters: lowercase a–z, digits 0–9, and dashes -.
  • Use one unique namespace per app/integration across all companies and projects.
  • Keep it consistent and simple (e.g., acme-invoice-sync).

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


Troubleshoot Webhooks

  • Nothing arriving? Confirm you created both a hook and at least one trigger at the same scope (company vs project) and payload version. For project events from a Project Level hook, confirm you created a hook on that project.
  • Seeing loops? Filter out events initiated by your service account or app using event metadata.
  • Many failures? Inspect each delivery_attempts entry’s response_status and response_body, confirm your endpoint returns 2xx on success, and that secrets/URLs are correct.
  • Wrong data? Double‑check resource_name values and your payload_version.


See Also

Was this page helpful? Thanks for your feedback!