Webhooks

Webhooks let Contractors Cloud notify your application the moment something happens, instead of you polling the API for changes. Create a webhook pointing at an HTTPS endpoint you control, subscribe it to one or more events, and Contractors Cloud sends a POST request with a JSON payload to that endpoint every time one of those events occurs.

Creating a webhook

curl -X POST "https://api.contractorscloud.com/api/v1/webhooks" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"endpoint": "https://example.com/webhooks/contractors-cloud", "company_id": 6}'

company_id is optional. Omit it (or send null) to receive matching events across every company in your organization, or set it to scope the webhook to a single company. The response includes a signing_secret:

{
  "id": "a3d8f2e6-1c4b-4a9d-8e3f-2b5a7c9d4f60",
  "tenant_id": 12,
  "company_id": 6,
  "user_id": 1159,
  "endpoint": "https://example.com/webhooks/contractors-cloud",
  "error_rate": 0,
  "is_enabled": true,
  "signing_secret": "5f2a9c3e8d1b6f4a7c2e9d5b3f8a1c6e4d7b2f9a",
  "created_at": "2025-02-11 09:00:00",
  "updated_at": "2025-02-11 09:00:00"
}

signing_secret is a credential — store it the way you’d store any other secret, and never expose it to a browser or client app. It’s returned on every response for this webhook (including list results), but there’s no separate endpoint to retrieve or rotate it. To change it, delete the webhook and create a new one.

See Create webhook for every field, and Update webhook and Delete webhook for managing it afterward — deleting a webhook also removes all of its event subscriptions and its entire delivery history.

Subscribing to events

A new webhook isn’t subscribed to anything by default. Discover the current catalog of events with List subscribable events:

curl "https://api.contractorscloud.com/api/v1/webhooks/subscribable-events" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Then subscribe your webhook to one with Create webhook event:

curl -X POST "https://api.contractorscloud.com/api/v1/webhooks/a3d8f2e6-1c4b-4a9d-8e3f-2b5a7c9d4f60/events" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"event": "projects.created"}'

A webhook can subscribe to as many events as you like, but only once each. The endpoint above is the authoritative list of what’s currently subscribable — treat the table below as a reference, not a substitute for checking it:

Event	Description
`projects.created`	Occurs whenever a Project is created. Currently, this event does not occur for Projects created through the Contractors Cloud Web App.
`projects.status.updated`	Occurs only when the status (status_id) of a Project is changed or updated.
`jet-streams.created`	Occurs whenever a Jet Stream is created.
`jet-streams.updated`	Occurs whenever a Jet Stream is updated.
`jet-streams.deleted`	Occurs whenever a Jet Stream is deleted.
`jet-streams.users.created`	Occurs whenever a new User is added to an existing Jet Stream.
`jet-streams.users.updated`	Occurs whenever the instance of where a User that corresponds to a Jet Stream is updated.
`jet-streams.users.deleted`	Occurs whenever a User is removed from a Jet Stream.
`jet-streams.replies.created`	Occurs whenever someone replies to a Jet Stream.
`jet-streams.replies.updated`	Occurs whenever a reply to a Jet Stream is updated.
`jet-streams.replies.deleted`	Occurs whenever a reply to a Jet Stream is deleted.

See the Webhook Events reference for listing, updating, and removing subscriptions.

Receiving deliveries

Every delivery is a POST request with a Content-Type: application/json body in the same envelope, regardless of event:

{
  "event": "projects.created",
  "description": "Occurs whenever a Project is created.",
  "webhook_id": "a3d8f2e6-1c4b-4a9d-8e3f-2b5a7c9d4f60",
  "data": {
    "id": 8842,
    "company_id": 6,
    "status_id": 2,
    "lead_id": null,
    "number": "2025-0142",
    "name": "Smith Residence - Roof Replacement",
    "account_name": "Jane Smith",
    "address_street": "482 Birchwood Ave",
    "address_city": "Madison",
    "address_state": "WI",
    "address_zip": "53703",
    "rep_primary_id": 1159,
    "amount_estimated": 18500,
    "created_at": "2025-02-10 09:15:00",
    "updated_at": "2025-02-10 09:15:00"
  }
}

data matches the shape of the corresponding resource returned elsewhere in the API — the example above is trimmed to representative fields; a real projects.created delivery includes the full project resource. Financial breakdown fields (such as financials_total_amount and expenses_total_amount) may be omitted from a project payload depending on the permissions of the user whose action triggered the event; amount_estimated and estimated_total_amount are always present. See the Project type for the full field list. Your endpoint has 10 seconds — connection and response combined — to return a 2xx status code. Returning anything else, or not responding in time, marks the delivery error or timeout respectively; see Retries for what happens next.

Verifying signatures

Every delivery carries a ContractorsCloud-Signature header so you can confirm it came from Contractors Cloud and wasn’t tampered with in transit:

ContractorsCloud-Signature: t=1739178903,v=8f1c3a7e9d2b6f4c1a8e3d7b9c2f5a6e4d1b8c3f2e9a5d0c7b4f8e1a6d3c9b25

t is the Unix timestamp the delivery was sent, and v is the hex-encoded HMAC-SHA256 signature of the string <t>.<raw request body>, computed with your webhook’s signing_secret as the key. To verify a delivery:

Extract t and v from the header.
Compute hash_hmac('sha256', "{t}.{raw_body}", signing_secret) against the raw request body bytes exactly as received — re-serializing the parsed JSON can reorder keys or change whitespace, which changes the signature.
Compare your computed value to v using a constant-time comparison, not == or string equality, to avoid leaking timing information.

Optionally, reject deliveries whose t is too old (for example, more than 5 minutes in the past) to reduce the window for replay attacks.

[$tPart, $vPart] = explode(',', $signatureHeader, 2);
$t = substr($tPart, 2); // "t=..." -> unix timestamp
$v = substr($vPart, 2); // "v=..." -> hex signature

// $rawBody must be the raw, unparsed request body, e.g. file_get_contents('php://input')
$expected = hash_hmac('sha256', "{$t}.{$rawBody}", $signingSecret);

if (!hash_equals($expected, $v)) {
    http_response_code(401);
    exit;
}

const crypto = require('crypto');

const [tPart, vPart] = signatureHeader.split(',');
const t = tPart.slice(2); // "t=..." -> unix timestamp
const v = vPart.slice(2); // "v=..." -> hex signature

// rawBody must be the raw, unparsed request body string or Buffer
const expected = crypto
  .createHmac('sha256', signingSecret)
  .update(`${t}.${rawBody}`)
  .digest('hex');

const expectedBuffer = Buffer.from(expected, 'hex');
const providedBuffer = Buffer.from(v, 'hex');

const isValid =
  expectedBuffer.length === providedBuffer.length &&
  crypto.timingSafeEqual(expectedBuffer, providedBuffer);

if (!isValid) {
  return res.status(401).end();
}

Retries

If a delivery comes back error or times out, Contractors Cloud automatically retries it up to 3 times: roughly 1 minute, then 15 minutes, then 60 minutes after the previous attempt. Each retry is a new send record with retry_parent_id pointing back at the attempt it retried, a fresh timestamp and signature, and the identical request body.

Deliveries aren’t guaranteed to arrive in order, and the same event can be delivered more than once (for example, if a retry and the original both eventually succeed). Design your endpoint to handle duplicate and out-of-order deliveries — for example, by keying off a stable field in data rather than assuming strict arrival order.

Testing and monitoring

Verify your endpoint and signature-checking logic without waiting for a real event, using Send test webhook:

curl -X POST "https://api.contractorscloud.com/api/v1/webhooks/a3d8f2e6-1c4b-4a9d-8e3f-2b5a7c9d4f60/sends" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

This takes no request body and always delivers the same fixed payload, with data set to {"id": "foo", "value": "bar"}. It works even if the webhook is disabled or has no event subscriptions yet, which makes it useful for confirming a new webhook is reachable before you subscribe it to anything. Every delivery attempt — test or real — is recorded as a webhook send, including the exact request body sent and the response your endpoint returned, retained for 365 days. List them with List webhook sends to audit past deliveries, and watch a webhook’s error_rate as an ongoing health signal for roughly the last 90 days of activity.

See the Webhooks reference for every field and status code, and Webhook send for the full shape of a delivery record.

Concepts

Domains

Examples

Creating a webhook

Subscribing to events

Receiving deliveries

Verifying signatures

Retries

Testing and monitoring

​Creating a webhook

​Subscribing to events

​Receiving deliveries

​Verifying signatures

​Retries

​Testing and monitoring

Creating a webhook

Subscribing to events

Receiving deliveries

Verifying signatures

Retries

Testing and monitoring