Procore Adapter CI Contract

Overview

Make offline fixtures the default CI denominator and isolate credentialed sandbox tests behind explicit protection. The gate should detect endpoint drift, first-page-only bugs, unsafe retries, tenant-routing loss, and secret leakage without mutating production.

Prerequisites

• Resource adapter inventory and current public endpoint references
• Sanitized success and failure fixtures with provenance
• Protected sandbox credential source and cleanup owner for optional live tests

Instructions

Step 1: Define contract cases

Cover required headers, request and response shapes, API version, pagination links, 401, 403, hidden 404, 422, 429, 503, and timeout behavior for each changed adapter.

Step 2: Add safety guards

Fail if a test selects production hosts, lacks explicit company context where required, prints Authorization data, or enables provider mutations outside a protected sandbox job.

Step 3: Test pagination and retries

Verify Link navigation reaches every fixture page and stops without next. Assert reset and retry headers control timing and writes are not replayed without reconciliation.

Step 4: Validate fixtures

Grep for secret patterns, customer identifiers, time-sensitive assertions, and undocumented routes. Require reviewed provenance when a fixture changes.

Step 5: Run bounded provider checks

Use a Developer Sandbox only when protected credentials are present. Create uniquely prefixed test data, record IDs, and clean it up; otherwise report the provider lane as skipped.

Step 6: Emit a gate receipt

Record release identifier, adapter set, fixture hashes, offline results, provider-lane status, cleanup result, and known gaps.

Authentication

Offline tests use synthetic tokens only. Optional provider checks obtain a sandbox OAuth 2.0 Bearer token from protected CI secrets, never expose it, and categorically reject production credentials and hosts.

Tool Discipline

Use Read and Grep to inspect adapters, fixtures, workflows, and logs. Use Write or Edit only for the approved test, fixture, CI configuration, or receipt; do not add unconditional network or production mutation steps.

Output

• Offline endpoint and failure contract gate
• Secret, host, routing, pagination, and retry safety results
• Optional sandbox-test and cleanup receipt

Return deterministic pass or fail, explicit skips, artifact hashes, and the exact adapter that regressed.

Examples

A pull request changing the RFI adapter replays sanitized success and error fixtures, proves Link pagination, and rejects production hosts. A protected nightly sandbox job creates one prefixed record and confirms cleanup without affecting required offline CI.

Error Handling

Procore Error Classification and Recovery

Overview

Classify failures by identity, company routing, authorization, endpoint contract, business validation, throttling, or provider health. Preserve the original response and avoid treating every 404 as absence or every 5xx as safe to retry.

Prerequisites

• Timestamp, environment, method, normalized route, status, and sanitized response
• Token alias, app version, company and project context, and operation type
• Current endpoint reference plus access to Integration Health or API activity evidence

Instructions

Step 1: Preserve the failure

Capture response code, headers, body shape, correlation data, and elapsed time. Redact authorization, destination headers, query secrets, names, and construction payloads.

Step 2: Classify the layer

Map 401 to token or environment; 403 to connection, permission, tool, or project scope; 404 to route, identifier, or concealed access; 422 to business validation; 429 to rate budget; and 5xx to provider or transient infrastructure.

Step 3: Check company routing

Verify the intended company and whether Procore-Company-Id is required. Audit background jobs and webhook handlers that may have lost explicit routing context.

Step 4: Check the public contract

Confirm the route, API version, required fields, filters, enabled tool, and project membership against current documentation. Reject private or deprecated endpoints.

Step 5: Recover narrowly

Refresh or reauthorize only for an identity failure, fix permissions only when evidence proves the missing permission, honor rate headers, and retry server errors only when the operation is safe.

Step 6: Verify the fix

Replay the smallest sanitized case, confirm the expected status and resource boundary, and monitor the relevant Integration Health observation or API activity slice.

Authentication

Troubleshooting uses the existing OAuth 2.0 Bearer token alias and never requests a broader token as a generic fix. Authorization Code and DMSA principals retain their existing permission models throughout diagnosis.

Tool Discipline

Use Read and Grep to inspect logs, adapters, manifests, and provider contracts. Use Write or Edit only for the approved fix, regression test, or redacted receipt; never store tokens or copy raw customer payloads into diagnostics.

Output

• Classified root cause with supporting provider evidence
• Narrow recovery and regression test
• Redacted before-and-after receipt

Return what failed, why, what changed, how access stayed bounded, and whether replay succeeded.

Examples

A project record that exists returns 404. Instead of changing the URL or granting admin access, the operator checks company routing, project membership, enabled tools, and rea…

Procore Governed RFI Lifecycle

Overview

Treat an RFI as a permissioned construction record with project configuration and business transitions, not generic CRUD. Derive fields and allowed actions from the current RFI reference and target project before submitting a mutation.

Prerequisites

• Target company and project identifiers with the RFI tool enabled
• OAuth principal permitted for the exact read or write operation
• Current RFI endpoint reference, project field configuration, and approval owner

Instructions

Step 1: Discover the project contract

List or show a representative RFI to confirm response shape, configurable fields, status values, and project access. Follow Link-header pagination for inventory reads.

Step 2: Build the intent

Capture subject, question, RFI manager, assignees, due-date policy, attachments, and notification choice. Resolve every referenced user or resource inside the same project.

Step 3: Validate without side effects

Check required fields against the live endpoint reference and project configuration. Present a sanitized mutation preview and require an identified approver.

Step 4: Execute once

Send the documented request only after approval. Record the response ID and status immediately; never infer success from a network timeout.

Step 5: Reconcile lifecycle

Read the RFI after each material transition. Drive responses, distribution, acceptance, or closure only through documented endpoints and fields rather than invented status strings.

Step 6: Preserve audit evidence

Store identifiers, before-and-after state hashes, actor, timestamp, and outcome without construction narrative or attachment contents.

Authentication

RFI calls use an OAuth 2.0 Bearer token and the required company routing context. Effective access comes from the user or DMSA permissions, project membership, and whether the RFI tool is enabled.

Tool Discipline

Use Read and Grep to inspect endpoint contracts, project configuration, and existing adapters. Use Write or Edit only for the approved adapter, test, mutation manifest, or redacted receipt; do not perform an unapproved RFI mutation.

Output

• Validated RFI intent and permission evidence
• Approved mutation plus read-after-write reconciliation
• Sanitized lifecycle and rollback receipt

Return the project, operation, RFI identifier, observed transition, approval reference, and unresolved dependencies.

Examples

A field issue becomes an RFI only after the integration resolves the project RFI manager and validates required fields. The service previews the request, records approval, creates once, and reads the returned record before notifying downstream systems.

Error Handling

Procore Version-Aware Submittal Workflow

Overview

Submittal endpoints coexist across versions and may expose beta surfaces. Select the documented version per operation, preserve company routing and notification controls, and reconcile workflow state instead of assuming a generic approve-or-reject contract.

Prerequisites

• Target company and project with Submittals enabled
• Current endpoint version and changelog reviewed for every intended operation
• Required managers, approvers, specification context, and notification policy resolved

Instructions

Step 1: Select the endpoint version

Open the current Submittals API reference and choose the supported route for the required operation. Record whether a surface is beta and obtain explicit risk acceptance before using it.

Step 2: Discover project data

List a bounded page of submittals and retrieve workflow data for a representative record. Capture required headers, fields, allowed filters, and pagination metadata.

Step 3: Validate the proposal

Resolve project users and specification references, obtain any next-number value through the documented endpoint, and make email behavior explicit. Never invent a workflow status.

Step 4: Approve the mutation

Render a sanitized request preview with target project, selected API version, recipients, and expected outcome. Require approval before creating or changing a submittal.

Step 5: Execute and reconcile

Send the mutation once, then fetch the submittal and its workflow data. Confirm the observed workflow state rather than trusting a local projection.

Step 6: Record compatibility

Keep endpoint-version selection in an adapter and test both current response fields and failure shapes so future migrations remain bounded.

Authentication

Submittal calls authenticate with an OAuth 2.0 Bearer token. Provide Procore-Company-Id wherever the endpoint reference requires it, and rely on the principal's project and Submittals permissions.

Tool Discipline

Use Read and Grep to inspect endpoint versions, workflow fields, and project configuration. Use Write or Edit only for the approved adapter, test, proposal, or receipt; do not perform an unapproved submittal mutation.

Output

• Endpoint-version and permission decision
• Validated submittal proposal and approval record
• Read-after-write workflow-state receipt

Return the selected route version, project, submittal identifier, notification choice, observed workflow state, and rollback owner.

Examples

Before creating a submittal, an adapter reads the current reference, requests the project's next available number, resolves the manager and approvers, and previews whether emails will be sent. It then reconciles the returned workflow data after appro…

Procore API Call Budget Recovery

Overview

Treat calls, worker time, transfer, and backlog as measured costs. Procore documents request limits and activity reporting, but not a universal per-call price, so financial claims must come from the operator's own infrastructure and agreement.

Prerequisites

• Route, method, status, and daily count from the API Call Activity Report
• Poll interval, worker utilization, transfer, storage, and queue metrics
• Freshness objective and correctness oracle for every optimized resource

Instructions

Step 1: Build the denominator

Rank normalized routes by total calls, failed calls, payload volume, and worker time. Separate unavoidable business traffic from retries, polling, and adapter defects.

Step 2: Eliminate failed-call waste

Fix recurring 400, 403, and 404 traffic first because unsuccessful requests consume rate budget. Remove private or deprecated routes rather than retrying them.

Step 3: Replace polling carefully

Use webhooks for prompt change notification and retain a lower-frequency reconciliation sync for completeness. Do not claim webhooks are a guaranteed event log.

Step 4: Collapse repeat reads

Cache stable company and project metadata, request collections instead of per-record reads, and use only documented filters, pagination, or sync actions.

Step 5: Quantify savings

Compare calls per useful changed record, failed-call share, compute time, transfer, backlog age, and infrastructure cost. Keep provider fees separate unless an authoritative contract supplies them.

Step 6: Guard freshness

Run a full reconciliation and compare state hashes. Roll back any optimization that misses records, delays required updates, or expands permissions.

Authentication

Optimized requests continue using the existing OAuth 2.0 Bearer token and company scope. Credential multiplication is not a cost or rate-control strategy and must never be used to bypass limits.

Tool Discipline

Use Read and Grep to inspect activity reports, metrics, call sites, and endpoint contracts. Use Write or Edit only for the approved optimization, test, budget, or receipt; do not modify Procore data during cost analysis.

Output

• Route-level waste and cost denominator
• Approved optimizations with correctness evidence
• Before-and-after API, infrastructure, freshness, and rollback metrics

Return measured savings and explicitly label any cost component that is unknown.

Examples

An hourly poll mostly returns unchanged RFIs while 404 retries consume capacity. The integration fixes the access defect, uses webhook notifications for prompt reads, and retains a nightly reconciliation that proves no records were missed.

Error Handling

Procore Governed File Transfer

Overview

Treat file bytes, upload sessions, returned storage instructions, resource association, and secure downloads as separate contracts. Never infer a permanent public URL or place customer documents in logs or diagnostic bundles.

Prerequisites

• Approved company, project, target resource, file classification, and retention period
• Current upload or document endpoint selected for the resource and file size
• OAuth principal with required tool access and encrypted staging storage

Instructions

Step 1: Inventory the transfer

Record source checksum, media type, size, logical owner, target resource, and duplicate policy. Reject unsupported or unclassified content before upload.

Step 2: Choose the documented flow

Use the current direct, segmented, unified, or resource-specific upload sequence documented for the target. Do not reuse a legacy upload contract merely because it returns an identifier.

Step 3: Upload to provider storage

Follow the returned storage request exactly, including method, fields, segment ordering, and completion step. Never send the Procore Bearer token to an unrelated storage host unless documentation explicitly requires it.

Step 4: Associate the upload

Use the documented upload identifier or attachment-by-reference shape for the target resource. Reconcile the resource after association.

Step 5: Download securely

Treat returned file URLs as opaque and potentially changing. Supply the Bearer token where secure-file guidance requires it and avoid persisting signed or redirect URLs.

Step 6: Verify and expire

Compare checksums or an approved content assertion, record association IDs, then remove temporary bytes and URLs according to retention policy.

Authentication

Procore resource and secure-file requests use an OAuth 2.0 Bearer token and required company context. Storage-upload authorization follows the provider-returned upload contract; do not leak the Procore token across hosts.

Tool Discipline

Use Read and Grep to inspect file metadata, endpoint contracts, and retention rules. Use Write or Edit only for the approved transfer adapter, manifest, test, or redacted receipt; never write customer bytes into source control.

Output

• Transfer and classification manifest
• Upload, association, download, and checksum evidence
• Temporary-storage deletion and retention receipt

Return identifiers and hashes, not file contents or signed URLs.

Examples

A drawing import creates the documented upload session, sends bytes to the returned storage destination, completes the upload, associates its upload ID with the target resource, verifies the resulting metadata, and deletes the encrypted staging copy.

Error Handling

Redacted Procore Diagnostic Manifest

Overview

Build a manifest of request metadata and assertions, not a raw archive. Procore support can investigate with method, URL, status, sanitized headers and body, and occurrence time; secrets and construction data increase risk without improving diagnosis.

Prerequisites

• Incident identifier, owner, audience, retention deadline, and approved destination
• Exact failing request window and normalized route
• Organization redaction rules for identities, projects, documents, and credentials

Instructions

Step 1: Declare collection scope

List the exact evidence fields required for the failure class. Reject recursive log directories, database dumps, environment files, OAuth responses, and attachment collections.

Step 2: Collect metadata

Capture UTC occurrence time, environment, method, normalized URL, status, elapsed time, API version, company and project aliases, rate headers, retry header, and application release identifier.

Step 3: Sanitize content

Remove Authorization and destination headers, client credentials, tokens, cookies, user details, project names, query secrets, request bodies, response payloads, and signed file URLs unless a reviewed minimal fragment is essential.

Step 4: Validate redaction

Grep the staged manifest for secret patterns and prohibited field names. Inspect every remaining value manually and replace provider identifiers with stable aliases where possible.

Step 5: Seal and transfer

Write a checksum, collector identity, scope statement, redaction result, expiry, and access list. Transfer only through the approved encrypted channel.

Step 6: Delete on schedule

Record the deletion owner and deadline, and preserve only the non-sensitive incident receipt after the diagnostic artifact expires.

Authentication

This workflow never acquires or refreshes OAuth credentials. Existing Bearer tokens, client secrets, refresh tokens, webhook destination headers, cookies, and signed URLs are prohibited from the manifest.

Tool Discipline

Use Read and Grep to inspect only the approved files and verify redaction. Use Write or Edit only for the bounded manifest and receipt; do not copy raw log trees or customer data into a new bundle.

Output

• Collection manifest and explicit exclusions
• Redaction verification and artifact checksum
• Transfer, access, retention, and deletion receipt

Return the artifact location by approved reference, never inline its sensitive contents.

Examples

For repeated 403 responses, the manifest includes the normalized endpoint, timestamps, status, app release, company and project aliases, and sanitized response message. It excludes the token, full request body, user names, and source log files.

Error Handling

Procore App Version Promotion

Overview

Promote the Procore app contract and the integration deployment as one reviewed release. Permission changes, installation steps, OAuth credentials, endpoint compatibility, and customer communication must align with the same semantic version.

Prerequisites

• Immutable integration release and matching Procore app version
• Permission and component diff, release notes, migration plan, and rollback owner
• Sandbox installation, test company, production approver, and observation window

Instructions

Step 1: Freeze the release

Record source release identifier, app manifest version, endpoint inventory, configuration schema, and generated artifacts. Refuse moving tags or unreviewed builds.

Step 2: Review contract changes

Classify semantic version impact and inspect added permissions, components, callback URLs, post-install steps, and customer-facing behavior.

Step 3: Verify in sandbox

Install the version using the correct environment key, exercise authentication, required reads, expected denials, mutations in disposable data, webhooks, and cleanup.

Step 4: Approve promotion

Present evidence, permission diff, release notes, known limitations, support plan, and rollback. Require the authorized operator to promote the reviewed version.

Step 5: Deploy and canary

Deploy the matching integration release to a bounded tenant set, verify token acquisition and read-only access, then enable controlled business processing.

Step 6: Observe and settle

Monitor API activity, Integration Health, errors, rate budget, webhook deliveries, and backlog. Roll back the application release or integration according to the predeclared boundary.

Authentication

Deployment verification uses OAuth 2.0 credentials for each environment and never copies sandbox tokens into production. Production credential issuance and rotation stay within the Developer Portal and approved secret store.

Tool Discipline

Use Read and Grep to inspect release artifacts, manifests, diffs, and evidence. Use Write or Edit only for the approved release record, configuration, test, or receipt; the actual Procore promotion requires an authorized portal operator.

Output

• Immutable release and app-version evidence
• Permission diff, sandbox proof, promotion approval, and canary results
• Observation, rollback, and customer-impact receipt

Return exact versions, approvers, test results, rollout scope, health signals, and final disposition.

Examples

A manifest adds a new project-tool permission, so the release is classified accordingly and tested against both allowed and denied projects. The production canary does not begin until the portal version and deployed integration share the reviewed release.

Error Ha…

Procore Permission and Project-Scope Governance

Overview

Procore access is the intersection of OAuth principal, tool permission, enabled project tool, project membership, permitted projects, and company routing. Manage these dimensions explicitly rather than treating a broad role label as the API contract.

Prerequisites

• User or DMSA identity and installed app version
• Complete endpoint, method, company, project, and data-classification inventory
• Current permission builder output and administrator for the target company

Instructions

Step 1: Map operations to tools

For each endpoint, record the company- or project-level Procore tool and minimum documented permission. Remove permissions that lack a current call-site owner.

Step 2: Review the DMSA manifest

Compare declared permissions with the inventory before releasing a new app version. Treat newly requested permissions as a reviewed contract change.

Step 3: Review permitted projects

List the projects selected during installation and compare them with the approved tenant scope. Remember that administrators may need to reconfigure permitted projects after app update or reinstall.

Step 4: Avoid manual drift

Use App Management and the intended manifest workflow. Investigate directory-level manual adjustments because they can diverge from app permissions and complicate upgrades.

Step 5: Test both sides

Run approved reads for required tools and expected-denial tests for an unpermitted project and an unnecessary operation. Treat excess access as a release blocker.

Step 6: Record approval

Capture app version, permission diff, project-scope diff, administrator decision, test results, and rollback procedure without exposing tenant data.

Authentication

API calls use OAuth 2.0 Bearer tokens. Authorization Code assumes the current user's permissions; DMSA Client Credentials assumes the DMSA permissions and permitted-project configuration established through installation.

Tool Discipline

Use Read and Grep to inspect manifests, endpoint requirements, and permission evidence. Use Write or Edit only for the approved map, manifest change, test, or receipt; do not grant or revoke Procore access without administrator approval.

Output

• Endpoint-to-tool permission matrix
• DMSA manifest and permitted-project diff
• Positive and negative authorization test evidence

Return unexplained permissions, missing access, excess access, approver, and safe rollback.

Examples

An RFI reader requests only the RFI tool's documented read permission and access to selected pilot projects. The release test proves the pilot is readable and a non-permitted project remains inaccessible before the manifest is promoted.

Error Handling

Procore Read-Only Connection Proof

Overview

Establish identity, company routing, project visibility, and pagination without creating construction records. The proof must demonstrate the selected environment and permission boundary, not merely that an access token exists.

Prerequisites

• Approved OAuth token obtained through the intended grant and environment
• Expected company identifier and at least one known permitted project
• Redacted evidence destination and named owner for permission failures

Instructions

Step 1: Freeze the target

Record the expected environment, API base, company ID, token alias, and app version. Reject mixed production and sandbox inputs before sending a request.

Step 2: Verify identity

Call the documented current-user or company discovery surface using the Bearer token. Supply Procore-Company-Id when the contract requires company routing, especially for multi-region and DMSA traffic.

Step 3: List visible projects

Use the documented projects list endpoint and a small page. Follow the returned pagination contract instead of assuming one page is complete.

Step 4: Assert the boundary

Confirm the known permitted project appears and a known unpermitted project does not. Treat excess visibility as a security defect rather than a successful smoke test.

Step 5: Capture a receipt

Record status, normalized route, company and project identifiers, page metadata, response latency, and a hash of the sanitized assertion output. Do not retain names or payloads unless the test requires them.

Authentication

Authenticate with an OAuth 2.0 Bearer token produced for the selected Procore environment. The token carries either user permissions or DMSA permissions; the smoke test never broadens those permissions.

Tool Discipline

Use Read and Grep to inspect environment configuration and expected identifiers. Use Write or Edit only for the approved test, assertion fixture, or redacted receipt; this workflow must not create, update, or delete Procore records.

Output

• Environment and identity assertion
• Company-routing and permitted-project assertion
• Pagination and negative-access assertion

Return pass or fail with the exact failed boundary and a secret-free receipt.

Examples

After a customer installs a DMSA app, the operator lists projects for that company and confirms the selected pilot project is visible. The test also confirms a non-permitted project is absent before the deployment is allowed to process events.

Error Handling

Procore Integration Incident Command

Overview

Protect construction data integrity while restoring service. Separate provider outage, identity failure, tenant-routing defect, permission drift, rate exhaustion, event-delivery gap, and internal deployment regression before choosing recovery actions.

Prerequisites

• Incident commander, severity, affected tenant aliases, start time, and objectives
• Current release, last known good release, queue and reconciliation checkpoints
• Procore status, Integration Health, API activity, and approved communication channels

Instructions

Step 1: Stabilize

Pause risky mutations, preserve durable queues, stop retry storms, and keep read-only evidence collection bounded. Do not delete events or rotate credentials without a matching hypothesis.

Step 2: Classify

Compare Procore status with route-level 401, 403, 404, 422, 429, 503, latency, webhook delivery, and backlog signals. Segment by release, environment, company, project, and operation.

Step 3: Test the boundary

Run one read-only connection proof using the intended principal and company context. Check app connection, DMSA permissions, permitted projects, enabled tools, and rate headers.

Step 4: Mitigate narrowly

Roll back a bad release, repair tenant routing, reauthorize or rotate only when credential evidence supports it, reduce concurrency, or disable the affected mutation path.

Step 5: Recover data

Determine the gap window, replay durable work idempotently, and run REST reconciliation. Validate record counts and state hashes before reopening downstream publication.

Step 6: Settle and learn

Monitor until objectives recover, record root cause and contributing controls, assign follow-ups, and retain only redacted evidence with a deletion schedule.

Authentication

Incident probes use the existing OAuth 2.0 principal unless identity failure is the proven cause. Tokens, client secrets, destination headers, and signed URLs never enter the incident timeline or chat.

Tool Discipline

Use Read and Grep to inspect telemetry, configurations, runbooks, and sanitized logs. Use Write or Edit only for the approved mitigation, recovery artifact, timeline, or receipt; consequential provider changes require the incident commander and administrator.

Output

• Classification, scope, timeline, and mitigation decision
• Gap-window reconciliation and parity evidence
• Root cause, rollback, follow-up, and redacted incident receipt

Return current severity, customer impact, safe action, owner, recovery signal, and next checkpoint.

Examples

Webhook deliveries fail during receiver downtime. The team preserves the queue, fixes ingress, identifies the exact gap window, reconciles changed resources through REST, compares downstrea…

Procore OAuth and DMSA Boundary

Overview

Select authentication from the actor model, not implementation convenience. User-facing applications normally use Authorization Code, while unattended connectors use Client Credentials through a Developer Managed Service Account whose manifest permissions bound access.

Prerequisites

• Named application owner and classified user-facing or headless workload
• Exact company-level and project-level tools the workload must access
• Approved callback, secret store, token cache, rotation owner, and revocation path

Instructions

Step 1: Choose the grant

Use Authorization Code when the integration acts as a Procore user. Use Client Credentials only for a DMSA or explicitly governed service account that operates without user context.

Step 2: Define least privilege

List required tool operations before building the app manifest. For a DMSA, encode only those company and project permissions, and require the administrator to select permitted projects during installation.

Step 3: Separate credentials

Keep production and Developer Sandbox credentials, tokens, login hosts, and API hosts isolated. Never accept a token minted for one environment in another environment's configuration.

Step 4: Implement token lifecycle

Exchange credentials only from a confidential backend, cache the returned Bearer token until its reported expiry, serialize refresh-token replacement for Authorization Code clients, and persist a newly rotated refresh token atomically.

Step 5: Prove the boundary

Run one permitted read and one expected-denial test. Include Procore-Company-Id where the endpoint or Multiple Procore Regions contract requires company routing.

Step 6: Revoke and rotate

Document how an operator revokes authorization, replaces credentials, observes the new credential, and removes the old one without logging secrets.

Authentication

Procore REST requests use OAuth 2.0 Bearer tokens. Authorization Code represents a logged-in user's permissions; Client Credentials represents a DMSA's configured permissions and permitted projects. Keep client secrets and tokens server-side, and never place them in evidence.

Tool Discipline

Use Read and Grep to inspect application manifests, endpoint requirements, and existing configuration. Use Write or Edit only for the approved configuration, code, test, or redacted receipt; do not change Procore permissions or installations without administrator approval.

Output

• Grant-selection decision and least-privilege permission inventory
• Environment-specific credential and token-lifecycle configuration
• Positive, negative, rotation, and revocation evidence with secrets removed

Return a concise receipt containing the app type, grant, enviro…

Procore Deterministic Development Loop

Overview

Separate fast fixture tests from deliberate provider tests. A Developer Sandbox supplies isolated seed data and separate OAuth credentials, but it is not a production replica and cannot be casually refreshed, so tests must own their records and cleanup.

Prerequisites

• Endpoint contract and failure case under test
• Sanitized request and response fixtures with stable identifiers
• Developer Sandbox app, sandbox credentials, and a dedicated test project
• Cleanup rule for every test-created Procore record

Instructions

Step 1: Define the contract

Capture method, normalized route, required headers, request schema, expected status, pagination metadata, and error shape. Keep provider-generated IDs outside golden assertions.

Step 2: Build fixture tests

Exercise token expiry, permission denial, hidden-resource 404, validation failure, throttling, and server retry behavior without network access. Assert that secrets and construction payloads are redacted.

Step 3: Isolate provider tests

Point live tests only at login-sandbox.procore.com and sandbox.procore.com with sandbox credentials. Refuse production hosts in local and CI test profiles.

Step 4: Create bounded data

Prefix test artifacts with a run identifier, record every created ID, and clean up in reverse dependency order. Do not assume the Developer Sandbox can be reset.

Step 5: Reconcile fixtures

When the official endpoint behavior changes, review the API reference and changelog, update the adapter first, then deliberately re-record only sanitized fixtures.

Authentication

Live sandbox tests use a sandbox OAuth 2.0 Bearer token. Production credentials and tokens are forbidden in the development profile, and recorded fixtures must contain neither credentials nor tokens.

Tool Discipline

Use Read and Grep to inspect code, fixtures, and endpoint documentation. Use Write or Edit only for the approved adapter, fixture, test, cleanup manifest, or receipt; provider mutations require a sandbox-only guard and cleanup path.

Output

• Endpoint contract and sanitized fixture set
• Offline test results plus bounded sandbox-test results
• Created-resource and cleanup receipt

Return fixture provenance, sandbox identifiers, assertions, cleanup outcome, and any documented provider drift.

Examples

An RFI adapter test replays sanitized 401, 403, 404, 422, and 429 fixtures offline. A separate sandbox case creates one prefixed RFI, verifies its response shape, records its ID, and removes it during teardown.

Error Handling

Procore Resumable Data Migration

Overview

Move records as an ordered, observable, and reversible program rather than a bulk request loop. Use documented resource contracts, stable external identity, supported sync actions, and separate file workflows while preserving tenant and project boundaries.

Prerequisites

• Source and target owners, data classification, retention, and legal approval
• Resource inventory, volume, dependency graph, field mapping, and unsupported-feature list
• DMSA or user permission map, rate budget, checkpoint store, and rollback boundary

Instructions

Step 1: Profile and map

Count records and files by company, project, resource, status, and dependency. Map required fields, codes, users, locations, permissions, timestamps, and external identifiers.

Step 2: Design stable identity

Use documented origin_id or equivalent only where the resource supports it. Define source-to-Procore mapping, collision handling, and a replay-safe uniqueness rule.

Step 3: Order dependencies

Create prerequisite company and project data before dependent records. Follow documented API call sequencing and isolate unsupported resources for explicit disposition.

Step 4: Execute resumably

Process bounded batches, follow rate headers, checkpoint after verified commits, and use sync actions only for supported resources. Transfer files through their separate documented upload and association flow.

Step 5: Reconcile continuously

Compare counts, key fields, relationships, file checksums, failures, duplicates, and state hashes per batch. Quarantine poison records without blocking the entire migration.

Step 6: Cut over and settle

Run final delta capture, freeze writes if required, verify parity, switch consumers, observe, and preserve rollback until the agreed settlement window closes.

Authentication

Migration calls use an OAuth 2.0 Bearer token for the approved user or DMSA and explicit company and project scope. The migration must not obtain broad permissions merely to simplify dependency handling.

Tool Discipline

Use Read and Grep to inspect mappings, contracts, checkpoints, and reconciliation evidence. Use Write or Edit only for the approved migration adapter, manifest, quarantine record, test, or receipt; never place source data in source control.

Output

• Resource map, dependency order, and unsupported-feature disposition
• Batch checkpoints, identity mappings, and failure quarantine
• Parity, cutover, rollback, and settlement receipt

Return migrated and failed counts, checkpoint, divergence summary, file verification, permission boundary, and next safe action.

Examples

A backfill creates prerequisite project metadata before RFIs, assigns stable external identity only on resources…

Procore Environment Isolation Matrix

Overview

Choose the environment from the test purpose and configure its actual installation and runtime contract. Developer, On-Demand, and Monthly sandboxes differ in credentials, hosts, app version keys, refresh behavior, and customer eligibility.

Prerequisites

• Test objective, data sensitivity, customer involvement, and refresh requirement
• App version, sandbox or production keys, OAuth credential aliases, and company IDs
• Named administrator and post-refresh or post-install verification owner

Instructions

Step 1: Select the environment

Use a Developer Sandbox for isolated app building, On-Demand Sandbox for customer-controlled testing on copied data, and Monthly Sandbox for a periodically refreshed customer snapshot. Use production only for approved live operation.

Step 2: Build an explicit matrix

Record authentication host, API host, browser host, app version key type, OAuth credential type, company ID, refresh behavior, and installation owner for each environment.

Step 3: Enforce isolation

Store configurations separately and add guards that reject mismatched host, credential alias, and environment. Never infer environment from a company name.

Step 4: Install correctly

Use the Sandbox App Version Key only for the Developer Sandbox. Customer On-Demand and Monthly sandboxes use the production app version key and must be installed or surfaced according to their documented lifecycle.

Step 5: Plan data reset

Do not assume Developer Sandboxes refresh. Treat On-Demand lifecycle as customer-controlled and Monthly Sandbox changes as disposable at refresh.

Step 6: Verify after change

After install, recreation, or refresh, obtain a token and run the read-only connection proof against the expected company and project boundary.

Authentication

Developer Sandbox uses sandbox OAuth credentials and sandbox hosts. On-Demand uses production OAuth credentials and production endpoints; Monthly uses production credentials with its monthly-sandbox hosts. Tokens are never interchangeable across configured environments.

Tool Discipline

Use Read and Grep to inspect environment matrices, app configuration, and guards. Use Write or Edit only for the approved configuration, test, runbook, or redacted receipt; installation changes require the proper Procore administrator.

Output

• Environment selection and complete connection matrix
• Host, key, credential, company, and reset guards
• Installation or refresh verification receipt

Return the environment, configuration aliases, expected data lifecycle, verification outcome, and owner.

Examples

A developer builds against a seeded Developer Sandbox with sandbox credentials. A customer trial uses an On-Demand Sandbox install…

Procore Integration Health Observability

Overview

Combine provider-side observations with application-side service signals. Procore's Integration Health and API Call Activity Report identify unhealthy response patterns and routes, while the integration must supply latency, backlog, freshness, reconciliation, and release context.

Prerequisites

• App owner with Developer Portal access and a recurring review cadence
• Normalized route, status, latency, retry, queue, webhook, and freshness telemetry
• Release identifiers, endpoint owners, alert destinations, and incident runbook

Instructions

Step 1: Export provider evidence

Review Integration Health and download the production API activity report. Preserve report time range, app identity, and a checksum in the audit receipt.

Step 2: Join route ownership

Map normalized route, method, status, and count to the responsible service and adapter. Flag unknown traffic as a legacy deployment or credential-compromise hypothesis.

Step 3: Monitor provider limits

Track rate limit, remaining budget, reset time, Retry-After, 401, 403, 404, 422, 429, and 5xx outcomes by route and release.

Step 4: Monitor data freshness

Track webhook acknowledgment and delivery outcomes, queue age, deduplication, reconciliation cursor age, changed records, and parity failures.

Step 5: Define actionable alerts

Every alert names the affected tenant boundary, route owner, runbook, severity, and recovery condition. Exclude tokens, payloads, names, and signed URLs.

Step 6: Close the loop

After remediation, verify application metrics and the provider observation history. Record when provider-side status may lag the underlying fix.

Authentication

Provider evidence is accessed through authorized Developer Portal sessions, while API probes use the intended OAuth 2.0 principal. Observability stores aliases and normalized metadata, never tokens or raw construction payloads.

Tool Discipline

Use Read and Grep to inspect reports, telemetry, releases, and runbooks. Use Write or Edit only for the approved dashboard, alert, mapping, or redacted receipt; do not broaden log collection to raw customer data.

Output

• Provider and application signal inventory
• Route ownership, objectives, alerts, and runbook links
• Health-review and remediation verification receipt

Return current health, dominant routes and failures, freshness risk, owner, action, and expected recovery signal.

Examples

An alert ties rising 403 counts on one normalized route to a specific adapter release and company alias. The operator fixes routing, verifies the error rate locally, and then watches the provider's daily health history catch up.

Error Handling

Procore Measured Sync Performance

Overview

Optimize useful records per request and end-to-end freshness before increasing concurrency. Procore recommends collection reads, caching, webhooks, and deliberate sequencing; page limits and response shapes remain endpoint-specific.

Prerequisites

• Baseline volume, latency percentiles, call count, error rate, and backlog age
• Resource dependency graph and current endpoint pagination contracts
• Correctness oracle for completeness, ordering, duplicates, and deletions

Instructions

Step 1: Measure the critical path

Group calls by normalized route and outcome. Identify serial dependency edges, repeated lookups, first-page-only defects, payload-heavy reads, and failed calls consuming budget.

Step 2: Sequence dependencies

Fetch company and project context before project resources, and prerequisite catalogs before dependent records. Avoid nested request waterfalls when one collection or cache can serve many records.

Step 3: Paginate correctly

Use each endpoint's documented per_page range and follow Link relations until next is absent. Never treat a global page-size recommendation as an endpoint guarantee.

Step 4: Reduce redundant work

Cache stable lookups, use webhooks for fast change detection, retain a periodic reconciliation scan, and use documented sync actions where the resource supports them.

Step 5: Tune concurrency

Increase workers gradually while observing rate headers, error rate, and provider latency. Route every worker through the shared rate controller.

Step 6: Verify correctness and gain

Compare record sets and state hashes before and after optimization. Accept the change only when completeness is unchanged and measured latency or call volume improves.

Authentication

Performance tests use the normal OAuth 2.0 Bearer token and company boundary. Never spread traffic across extra credentials to hide inefficient behavior or bypass provider controls.

Tool Discipline

Use Read and Grep to inspect traces, endpoint contracts, and synchronization code. Use Write or Edit only for the approved optimization, test, measurement, or receipt; avoid uncontrolled production load tests.

Output

• Before-and-after latency, volume, error, and backlog measurements
• Correctness comparison and endpoint-specific pagination evidence
• Accepted change, rejected experiments, and rollback threshold

Return the bottleneck, hypothesis, measured result, correctness verdict, and operational limit.

Examples

A connector replaces per-record project lookups with one cached collection, follows every Link next relation, and uses webhook events to prioritize changed records. A reconciliation scan still proves completeness after miss…

Procore Production Readiness Gate

Overview

Convert launch claims into verifiable evidence. This gate covers the integration and its Procore app contract; it does not declare Marketplace approval or provider certification merely because local checks pass.

Prerequisites

• Immutable release candidate and matching app version
• Data classification, permission map, environment matrix, and endpoint inventory
• Support, security, operations, rollback, and customer communication owners

Instructions

Step 1: Verify application contract

Confirm semantic version, release notes, components, callbacks, permissions, permitted-project behavior, installation instructions, and production credentials.

Step 2: Verify functional paths

Exercise token lifecycle, required reads, expected denials, approved mutations, pagination, files, webhooks, deduplication, reconciliation, and cleanup in the intended sandbox.

Step 3: Verify reliability

Prove handling for 401, 403, hidden 404, 422, 429, 503, timeout, ambiguous write, duplicate event, discarded event window, and provider outage.

Step 4: Verify security and privacy

Review secret storage and rotation, tenant routing, least privilege, log redaction, secure-file handling, data retention, deletion, and incident escalation.

Step 5: Verify operations

Establish Integration Health and API activity review, rate and backlog alerts, support intake, status-page dependency, runbooks, and on-call ownership.

Step 6: Decide explicitly

Record PASS, CONDITIONAL, or FAIL per gate with evidence. Require launch approval and preserve rollback triggers; do not convert missing evidence into a pass.

Authentication

Readiness tests use the selected OAuth 2.0 grant, environment-specific credentials, and intended user or DMSA permission boundary. Evidence excludes all tokens, client secrets, and webhook destination credentials.

Tool Discipline

Use Read and Grep to inspect release artifacts, tests, manifests, and evidence. Use Write or Edit only for the approved checklist, remediation, test, or redacted receipt; passing this workflow does not authorize provider-side promotion.

Output

• Evidence matrix for application, function, reliability, security, and operations
• Explicit gaps, owners, rollback triggers, and approval
• Launch or no-launch decision with provider-certification boundary

Return exact release identifiers, gate verdicts, evidence references, approvers, and unresolved risks.

Examples

A release passes happy paths but lacks proof for discarded webhook recovery. The gate remains conditional until a bounded outage test shows reconciliation closes the gap; it does not award itself Procore Marketplace approval.

Error Handling

Procore Header-Driven Rate Controller

Overview

Control throughput from the headers on each response instead of a hard-coded request count. Procore exposes whichever spike or hourly window is most likely to bind, and failed requests consume the same budget as successful calls.

Prerequisites

• Central request dispatcher with observable worker concurrency
• Durable queue and a clock synchronized well enough to interpret reset timestamps
• Metrics for status, route, remaining budget, reset time, retries, and backlog age

Instructions

Step 1: Capture every budget signal

Record X-Rate-Limit-Limit, X-Rate-Limit-Remaining, and X-Rate-Limit-Reset from each response. Preserve Retry-After for heavy-load responses.

Step 2: Pace before exhaustion

Reduce dispatch concurrency as remaining budget falls and pause when it reaches zero. Treat the current headers as authoritative for either the spike or hourly window.

Step 3: Handle throttling

On 429, wait until after the reported reset and add jitter before resuming. On 503, obey Retry-After; never substitute an assumed delay.

Step 4: Bound retries

Retry safe reads within a capped policy. For writes, reconcile outcome or require an operation-specific idempotency design before another attempt.

Step 5: Protect event backlogs

Acknowledge webhook notifications quickly, enqueue downstream reads, and let the controller drain them. Monitor oldest-event age as well as queue depth.

Step 6: Prove recovery

Test low-budget, exhausted-budget, 429, and 503 fixtures. Verify one worker cannot bypass the shared controller and that recovery does not release a synchronized surge.

Authentication

Requests retain their existing OAuth 2.0 Bearer token and company routing. Throttling must not acquire alternate credentials to evade a rate boundary or log tokens alongside rate metadata.

Tool Discipline

Use Read and Grep to inspect dispatcher code, metrics, and provider headers. Use Write or Edit only for the approved limiter, queue policy, tests, or receipt; do not generate live load as a rate-limit test.

Output

• Header-driven pacing and retry policy
• Deterministic limit and recovery tests
• Route-level budget, backlog, and failure metrics

Return the observed headers, controller decision, retry eligibility, next dispatch time, and verification outcome.

Examples

When remaining budget reaches zero, all workers stop until the reported reset plus jitter. A 503 follows its Retry-After value, while an ambiguous write is reconciled rather than replayed with the safe-read policy.

Error Handling

Procore Governed Connector Architecture

Overview

Separate identity, tenant routing, ingestion, hydration, reconciliation, mutation approval, and audit evidence. Procore webhooks improve freshness but REST remains the data source, so the architecture must tolerate duplicates, delays, missed notifications, and partial writes.

Prerequisites

• Source and destination ownership, data domains, classification, and residency constraints
• Freshness, completeness, recovery, and deletion objectives
• OAuth grant, DMSA permission map, environment matrix, and endpoint inventory

Instructions

Step 1: Draw trust boundaries

Identify token service, ingress, queue, workers, state store, outbound adapters, audit sink, and operator interface. Carry company and project context as immutable job attributes.

Step 2: Separate adapter contracts

Keep endpoint version, request schema, pagination, rate metadata, and errors inside resource adapters. Do not create one fictional global Procore API version.

Step 3: Design dual ingestion

Accept webhook notifications into a durable queue for freshness. Hydrate current resources through REST and run periodic cursor-based reconciliation for completeness.

Step 4: Make processing idempotent

Deduplicate events, use origin identifiers or documented sync actions where supported, maintain checkpoints, and reconcile ambiguous mutations before retrying.

Step 5: Govern writes

Validate scope, render a preview, obtain approval where required, execute once, read after write, and emit a redacted receipt. Keep read and write worker authority separable.

Step 6: Prove failure behavior

Test token expiry, tenant-routing loss, duplicate and discarded events, rate exhaustion, provider outage, poison records, rollback, and replay from checkpoints.

Authentication

The token service obtains OAuth 2.0 credentials for the intended user or DMSA boundary and injects Bearer tokens only at dispatch. Every job retains explicit company and project routing without logging tokens.

Tool Discipline

Use Read and Grep to inspect topology, data contracts, and existing controls. Use Write or Edit only for the approved architecture, adapter contract, test plan, or receipt; no provider mutation is implied by architecture work.

Output

• Trust-boundary and data-flow design
• Endpoint, queue, checkpoint, reconciliation, and permission contracts
• Failure, rollback, replay, and observability plan

Return decisions, rejected alternatives, assumptions, owners, and measurable acceptance criteria.

Examples

A webhook receiver queues only event metadata and acknowledges quickly. A tenant-bound worker hydrates the current record through a versioned adapter, deduplicates it, updates downstream state, and advances a checkpoin…

Procore Contract-Preserving REST Client

Overview

Keep the client transport-focused and endpoint versions explicit. Procore resources use multiple REST versions, endpoint-specific page limits, company routing requirements, and actionable response headers that a generic JSON wrapper must not erase.

Prerequisites

• Enumerated public endpoints and their current reference versions
• Token-provider interface that never exposes client secrets to callers
• Typed error, pagination, rate-budget, and redaction contracts

Instructions

Step 1: Model requests explicitly

Represent HTTP method, full documented route, API version, company ID, project ID, query parameters, and body separately. Reject private or guessed routes.

Step 2: Centralize safe headers

Add the Bearer token at dispatch time. Carry Procore-Company-Id from explicit request context where required, and never infer company routing from a cached payload.

Step 3: Preserve response metadata

Return status, parsed body, request correlation data, Link, Total, Per-Page, X-Rate-Limit-*, and Retry-After to higher layers.

Step 4: Bound retries

Retry only safe reads or mutations with a proven idempotency design. Honor reset or retry headers, add jitter, cap attempts, and surface the final provider response.

Step 5: Test endpoint adapters

Give each resource adapter contract fixtures for success, pagination, permission denial, validation errors, throttling, and server failure. Keep business workflows outside the transport.

Authentication

The client receives OAuth 2.0 Bearer tokens from an external token provider and injects them only at request dispatch. It must not accept client secrets as ordinary endpoint parameters or log authorization headers.

Tool Discipline

Use Read and Grep to inspect existing transports, endpoint references, and call sites. Use Write or Edit only for the approved client, adapter, tests, or receipt; do not silently rewrite business workflows or provider data.

Output

• Typed transport and endpoint adapter boundary
• Pagination, throttling, error, and redaction tests
• Endpoint-version inventory and upgrade ownership

Return which response contracts are preserved and which endpoints remain outside the client.

Examples

A submittals adapter selects the documented submittals version explicitly and returns Link-header pagination to the caller. The shared transport adds routing and auth headers, but it does not pretend all resources share that version or page size.

Error Handling

Procore Integration Security Boundary

Overview

Protect construction data by constraining identity, company and project scope, transport, stored artifacts, and operator actions. Procore authorization is permission-based; neither a valid token nor a successful request proves least privilege.

Prerequisites

• Data-flow diagram, asset classification, trust boundaries, and named security owner
• OAuth grant, credential locations, DMSA manifest, and permitted-project inventory
• Webhook destinations, file flows, log sinks, support path, and revocation procedure

Instructions

Step 1: Inventory secrets and principals

Locate client secrets, access and refresh tokens, webhook destination secrets, cookies, and signed URLs. Ensure each secret has an owner, approved store, rotation path, and narrow audience.

Step 2: Prove least privilege

Map every endpoint to its required Procore tool permission and project scope. For DMSAs, compare the manifest with installed permitted projects and remove unexplained access.

Step 3: Bind company routing

Carry company context explicitly and validate Procore-Company-Id where required. Prevent a multi-company worker or event handler from reusing stale tenant context.

Step 4: Protect data paths

Use supported TLS, authenticate secure-file downloads as documented, sanitize logs and traces, and keep payload retention proportional to the business requirement.

Step 5: Harden mutations

Separate preview from execution, require approval for consequential changes, validate project ownership, and reconcile provider state after writes.

Step 6: Exercise response

Test revocation, credential rotation, app disconnection, webhook-secret rotation, and audit retrieval. Record recovery time without exposing the secrets under test.

Authentication

Procore API access uses OAuth 2.0 Bearer tokens from Authorization Code or DMSA Client Credentials. Store client secrets server-side, rotate credentials regularly, and revoke authorization when access is no longer valid.

Tool Discipline

Use Read and Grep to inspect architecture, manifests, configuration, and evidence. Use Write or Edit only for the approved threat model, security change, test, or redacted receipt; provider permission changes require administrator approval.

Output

• Threat model and endpoint-to-permission map
• Secret, routing, file, webhook, and mutation controls
• Rotation, revocation, and negative-access test evidence

Return risks by severity, bounded remediation, owner, due condition, and verification status.

Examples

A multi-company connector passes company context with every job and tests that a permitted DMSA cannot read an unselected project. Logs retain normalized routes and status codes while excluding toke…

Procore Endpoint Contract Cutover

Overview

Migrate the concrete resource and operation named by provider evidence. Procore does not expose one universal pack-wide version transition, so never claim a generic v1-to-v1.1 upgrade without endpoint-specific documentation.

Prerequisites

• Deprecated route, method, version, or payload format and documented replacement
• API Call Activity Report slice covering every deployed caller
• Old and new response contracts, test fixtures, rollout owner, and removal deadline

Instructions

Step 1: Prove affected traffic

Find the normalized deprecated route in production activity and search every service, scheduled job, event handler, and shared adapter for callers.

Step 2: Diff contracts

Compare paths, headers, IDs, query parameters, request fields, response fields, pagination, permissions, status codes, webhook schema, and lifecycle phase.

Step 3: Build a compatibility adapter

Isolate the new contract behind a resource-specific interface. Normalize only fields the business layer truly needs and preserve provider errors and metadata.

Step 4: Verify side by side

For reads, compare sanitized result sets and state hashes. For writes, use sandbox fixtures or a provider-supported idempotent strategy; do not duplicate live mutations.

Step 5: Roll out by cohort

Canary the new adapter, monitor error and rate signals, and keep an explicit rollback boundary while the old route remains supported.

Step 6: Remove the old path

After traffic evidence reaches zero and the observation clears, remove compatibility code, fixtures, configuration, and documentation for the deprecated contract.

Authentication

Both contracts use the intended OAuth 2.0 principal and company boundary. A migration must not widen DMSA permissions or switch grant types unless that separate security change is reviewed.

Tool Discipline

Use Read and Grep to inspect changelogs, activity reports, adapters, and callers. Use Write or Edit only for the approved adapter, migration test, rollout configuration, or receipt; do not perform duplicate live writes.

Output

• Provider evidence and complete caller inventory
• Contract diff, compatibility adapter, and equivalence tests
• Canary, rollback, zero-traffic, and removal receipt

Return the exact old and new contracts, affected volume, semantic differences, rollout status, and deletion evidence.

Examples

A deprecated webhook route is still called by one monthly job. The team adds the documented scoped replacement, verifies payload and permission differences, canaries it, and removes the legacy route only after the API activity report shows no callers.

Error Handling

Procore Webhook and Reconciliation Boundary

Overview

Use webhooks for freshness and REST reconciliation for completeness. A delivery tells the receiver that a committed Procore change occurred; it is not the resource itself and may be duplicated, delayed, or discarded after prolonged endpoint failure.

Prerequisites

• Company or project scope, namespace, resource names, and event reasons
• Public HTTPS receiver that acknowledges quickly and queues work durably
• Webhooks API permission, OAuth principal, deduplication store, and reconciliation cursor

Instructions

Step 1: Choose payload format

Use the current recommended payload format for new integrations and record the schema contract. Treat string identifier changes and renamed event fields as a versioned migration.

Step 2: Create the hook

Create one company- or project-scoped hook with an HTTPS destination, required namespace, minimal destination headers, and no secrets in logs.

Step 3: Add bounded triggers

Subscribe only to documented resources and reasons the application processes. Verify hook and trigger state through the documented API.

Step 4: Acknowledge and queue

Validate structure, record the event identifier, enqueue a follow-up read, and return a success response within the provider timeout. Process business work asynchronously.

Step 5: Deduplicate and hydrate

Use event ID or ULID according to the chosen payload. Fetch the current resource from REST and make downstream processing idempotent.

Step 6: Reconcile gaps

Monitor deliveries and run periodic REST scans from a durable cursor. Explicitly repair the gap after endpoint failure or discarded notifications.

Authentication

Webhook configuration calls use an OAuth 2.0 Bearer token with Webhooks API permission. Destination authentication uses only minimal reviewed headers; never log those headers or confuse them with Procore OAuth credentials.

Tool Discipline

Use Read and Grep to inspect handler code, delivery evidence, and endpoint contracts. Use Write or Edit only for the approved hook manifest, handler, test, cursor, or receipt; provider-side hook changes require explicit approval.

Output

• Hook, trigger, payload-version, and permission manifest
• Receiver, deduplication, hydration, and reconciliation evidence
• Delivery health, gap window, and recovery receipt

Return scope, namespace, payload version, trigger set, acknowledgment result, and reconciliation checkpoint.

Examples

An RFI update delivery is acknowledged and queued immediately. A worker deduplicates by the versioned event identifier, retrieves the current RFI, and updates downstream state; a periodic scan catches any notification lost during receiver downtime.

Error Handling