Webhooks

CrewLink can POST a signed JSON event to your server whenever something happens to a company's schedule: a booking is made, moved or cancelled, a tech is on the way, a job is done, a deposit or invoice is paid, a review comes in, a CrewConnect partner connects. Use them to keep your CRM, website or field tools in step without polling.

• Subscribing
• What a delivery looks like
• Verifying signatures (Node, Python, PHP)
• Retries
• Ordering and duplicates
• Events
• Testing locally

#Subscribing

Endpoints belong to a company. Adding and removing them needs the owner role (the company API key or an owner's token); dispatchers can list them. A platform with the webhooks scope can add its own endpoints for a company (listed with platform set to its slug, removed when the company revokes it), or keep one platform-wide subscription for every company that granted it (POST /v1/platform/webhooks). Each endpoint has its own secret, shown once when it is made.

#POST /v1/office/webhooks

curl -X POST $CREWLINK/v1/office/webhooks \
  -H "authorization: Bearer $KEY" -H 'content-type: application/json' \
  -d '{"url": "https://hooks.example.com/crewlink", "events": ["booking.created", "booking.rescheduled", "booking.cancelled"]}'

201

{
  "id": "6f1c2a7e-3b9d-4c51-9a0e-2d8f4b7c1e93",
  "url": "https://hooks.example.com/crewlink",
  "events": ["booking.created", "booking.rescheduled", "booking.cancelled"],
  "active": true,
  "historyEvents": false,
  "platform": null,
  "secret": "whsec_<signing secret>"
}

secret is shown once. Store it; it signs every delivery to this endpoint.

URL rules, checked when you add the endpoint and again before every delivery:

• https only, with a host name (not an IP address) and no user name or password in it.
• The host must be on the public internet: names like localhost, *.local, *.internal, *.lan, *.corp and single-label names are refused, and so is any name that resolves to a private, loopback, link-local, carrier-grade NAT, multicast or reserved address.
• Port 443 or 8443, unless the host already resolves to a public address (then any port).
• Redirects are never followed. A 3xx answer counts as a failed delivery, so point the endpoint at the final URL.

#GET /v1/office/webhooks

Owner or dispatcher.

{
  "endpoints": [
    { "id": "6f1c2a7e-3b9d-4c51-9a0e-2d8f4b7c1e93", "url": "https://hooks.example.com/crewlink", "events": ["booking.created", "booking.rescheduled", "booking.cancelled"], "active": true, "historyEvents": false, "platform": null }
  ]
}

#PATCH /v1/office/webhooks/{id}

Owner only (the company API key, an owner's token, or a platform key with webhooks for an endpoint that platform made). Changes one endpoint in place: its event list, and whether it gets the history emissions. The id, URL and signing secret stay the same. Deliveries already queued are not changed. Send either field or both.

curl -X PATCH $CREWLINK/v1/office/webhooks/6f1c2a7e-3b9d-4c51-9a0e-2d8f4b7c1e93 \
  -H "authorization: Bearer $KEY" -H 'content-type: application/json' \
  -d '{"historyEvents": true}'

200: the endpoint as listed, { "id", "url", "events", "active", "historyEvents": true, "platform" }.

Errors: 401, 403 forbidden (not an owner), 404 not_found (not this company's endpoint; on a platform key, not one that platform made), 422 invalid_request (neither field sent, an unknown event, or an empty list).

A platform's platform-wide subscription is changed with PATCH /v1/platform/webhooks/{id} (same body and answer, without platform).

#DELETE /v1/office/webhooks/{id}

Owner only. Removes the endpoint; deliveries still waiting for it are dropped.

{ "id": "6f1c2a7e-3b9d-4c51-9a0e-2d8f4b7c1e93", "deleted": true }

Errors: 401, 403 forbidden, 404 not_found.

#GET /v1/office/webhooks/{id}/deliveries

Owner only. The endpoint's delivery log, newest first: every event queued for it, how many attempts were made, the last HTTP status and error, when it goes next, and the body exactly as sent. Use it to tell "never queued" from "queued but your server didn't answer 2xx". A platform key sees only the endpoints it subscribed; a platform's platform-wide subscription has the same log at GET /v1/platform/webhooks/{id}/deliveries. 404 not_found for an endpoint that isn't yours.

Query (all optional):

curl -s "$CREWLINK/v1/office/webhooks/6f1c2a7e-3b9d-4c51-9a0e-2d8f4b7c1e93/deliveries?jobId=1042" -H "Authorization: Bearer $KEY"

{
  "deliveries": [
    {
      "id": 58214,
      "endpointId": "6f1c2a7e-3b9d-4c51-9a0e-2d8f4b7c1e93",
      "event": "booking.cancelled",
      "companyId": "8a1f0c3e-2b4d-4e6f-9a8b-7c6d5e4f3a2b",
      "status": "pending",
      "createdAt": "2026-10-12T17:45:00.000Z",
      "attempts": 2,
      "lastAttemptAt": "2026-10-12T17:46:01.000Z",
      "nextAttemptAt": "2026-10-12T17:51:01.000Z",
      "lastStatusCode": 404,
      "lastError": "HTTP 404",
      "deliveredAt": null,
      "payload": { "id": 58214, "event": "booking.cancelled", "createdAt": "2026-10-12T17:45:00.000Z", "companyId": "8a1f0c3e-2b4d-4e6f-9a8b-7c6d5e4f3a2b", "data": { "bookingId": 1042, "jobId": 1042, "source": "office", "status": "cancelled", "...": "..." } }
    },
    {
      "id": 58213,
      "endpointId": "6f1c2a7e-3b9d-4c51-9a0e-2d8f4b7c1e93",
      "event": "booking.created",
      "companyId": "8a1f0c3e-2b4d-4e6f-9a8b-7c6d5e4f3a2b",
      "status": "delivered",
      "createdAt": "2026-10-12T15:30:00.000Z",
      "attempts": 1,
      "lastAttemptAt": "2026-10-12T15:30:04.000Z",
      "nextAttemptAt": null,
      "lastStatusCode": 200,
      "lastError": null,
      "deliveredAt": "2026-10-12T15:30:04.000Z",
      "payload": { "id": 58213, "event": "booking.created", "...": "..." }
    }
  ],
  "next": null
}

Deliveries are kept; the log goes back to the endpoint's first event. Errors: 401, 403 forbidden (not an owner), 404 not_found.

#POST /v1/office/webhooks/{id}/deliveries/{deliveryId}/retry

Owner only. Queues one delivery again, due now, whatever its status (a delivered one is sent again too). It keeps its id and body; the send loop picks it up within about 10 seconds. attempts is kept, so one that had been given up and fails again is given up again (retry it again once your server is fixed). Answers the delivery as in the log (status: "pending"). Errors: 401, 403 forbidden, 404 not_found (no such endpoint, or no such delivery for it).

Rotating a secret: add a second endpoint with the same URL and events, accept signatures from either secret for a moment, then delete the old endpoint. During the overlap each event arrives twice (once per endpoint, with different delivery ids), so make sure your handler skips duplicates by booking or job as well as by delivery id.

#What a delivery looks like

Each event is one POST to your URL:

POST /crewlink HTTP/1.1
Host: hooks.example.com
Content-Type: application/json
CrewLink-Event: booking.created
CrewLink-Delivery: 58213
CrewLink-Signature: t=1791817800,v1=5f0c3a1d9e8b7c6a5f4e3d2c1b0a99887766554433221100ffeeddccbbaa9988

{"id":58213,"event":"booking.created","createdAt":"2026-10-12T15:30:00.000Z","companyId":"8a1f0c3e-2b4d-4e6f-9a8b-7c6d5e4f3a2b","data":{"bookingId":1042,"jobId":1042,"source":"booking_page","status":"booked","serviceId":2,"service":"Repair visit","start":"2026-10-13T19:30:00.000Z","local":"2026-10-13T14:30","end":"2026-10-13T21:00:00.000Z","localEnd":"2026-10-13T16:00","timezone":"America/Chicago","techs":[3],"clientCompanyId":null,"client":null,"externalRef":null,"externalSource":null,"externalRefs":{}}}

Body:

Answer with any 2xx within 10 seconds. Anything else (3xx, 4xx, 5xx, a timeout, a refused connection) is a failed attempt and is retried. Do the real work after you answer: put the event on a queue, return 200, then process it.

Ids in data (bookingId, jobId, techs, personId) are the same ids the rest of the API uses. techs and personId are tech ids from GET /v1/office/team.

#Verifying signatures

Every delivery is signed with the endpoint's secret so you can tell it came from CrewLink and wasn't changed:

CrewLink-Signature: t=1791817800,v1=5f0c3a1d...

• t is the Unix time (seconds) when this attempt was sent. It changes on each retry.
• v1 is the hex HMAC-SHA256 of the string "<t>.<raw body>", keyed with the whole secret (including the whsec_ prefix).

To verify:

1. Read the raw request body bytes. Don't parse and re-serialize the JSON first: any change in spacing or key order breaks the signature.
2. Split the header on , and each part on the first =, and take t and v1.
3. Compute HMAC-SHA256 of t + "." + rawBody with your secret, as lowercase hex.
4. Compare it with v1 in constant time.
5. Reject the delivery if t is more than 5 minutes from your clock, so a captured request can't be replayed later.

Answer 400 or 401 when verification fails; CrewLink will retry, which is what you want if the failure was on your side.

#Node.js

// npm i express
import crypto from 'node:crypto';
import express from 'express';

const SECRET = process.env.CREWLINK_WEBHOOK_SECRET; // whsec_...

export function verifyCrewLink(rawBody, header, secret, toleranceSeconds = 300) {
  if (!header) return false;
  const parts = Object.fromEntries(
    header.split(',').map((p) => {
      const i = p.indexOf('=');
      return [p.slice(0, i).trim(), p.slice(i + 1).trim()];
    }),
  );
  const t = Number(parts.t);
  if (!Number.isInteger(t) || !parts.v1) return false;
  if (Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${t}.`).update(rawBody).digest('hex');
  const a = Buffer.from(expected, 'utf8');
  const b = Buffer.from(parts.v1, 'utf8');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

const app = express();
const seen = new Set(); // use your database in production

// express.raw keeps the body as a Buffer, exactly as sent.
app.post('/crewlink', express.raw({ type: 'application/json' }), (req, res) => {
  if (!verifyCrewLink(req.body, req.get('crewlink-signature'), SECRET)) return res.sendStatus(401);
  const event = JSON.parse(req.body.toString('utf8'));
  res.sendStatus(200); // answer first
  if (seen.has(event.id)) return; // a retry of something already handled
  seen.add(event.id);
  queueMicrotask(() => handle(event));
});

function handle(event) {
  switch (event.event) {
    case 'booking.created':
      console.log('new booking', event.data.bookingId, 'at', event.data.local);
      break;
    case 'booking.cancelled':
      console.log('cancelled', event.data.bookingId);
      break;
  }
}

app.listen(3000);

#Python

# pip install flask
import hashlib, hmac, json, os, time
from flask import Flask, request, abort

SECRET = os.environ["CREWLINK_WEBHOOK_SECRET"]  # whsec_...
app = Flask(__name__)

def verify_crewlink(raw_body: bytes, header: str | None, secret: str, tolerance: int = 300) -> bool:
    if not header:
        return False
    parts = dict(p.strip().split("=", 1) for p in header.split(",") if "=" in p)
    try:
        t = int(parts["t"])
        v1 = parts["v1"]
    except (KeyError, ValueError):
        return False
    if abs(time.time() - t) > tolerance:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, v1)

@app.post("/crewlink")
def crewlink():
    raw = request.get_data()  # the raw bytes; don't use request.json before verifying
    if not verify_crewlink(raw, request.headers.get("CrewLink-Signature"), SECRET):
        abort(401)
    event = json.loads(raw)
    # enqueue event for processing, skipping ids you've already handled
    print(event["event"], event["data"])
    return "", 200

#PHP

<?php
// crewlink.php
$secret = getenv('CREWLINK_WEBHOOK_SECRET'); // whsec_...

function verify_crewlink(string $rawBody, ?string $header, string $secret, int $tolerance = 300): bool {
    if (!$header) return false;
    $parts = [];
    foreach (explode(',', $header) as $part) {
        $kv = explode('=', trim($part), 2);
        if (count($kv) === 2) $parts[$kv[0]] = $kv[1];
    }
    if (!isset($parts['t'], $parts['v1']) || !ctype_digit($parts['t'])) return false;
    $t = (int) $parts['t'];
    if (abs(time() - $t) > $tolerance) return false;
    $expected = hash_hmac('sha256', $t . '.' . $rawBody, $secret);
    return hash_equals($expected, $parts['v1']);
}

$raw = file_get_contents('php://input');
if (!verify_crewlink($raw, $_SERVER['HTTP_CREWLINK_SIGNATURE'] ?? null, $secret)) {
    http_response_code(401);
    exit;
}
$event = json_decode($raw, true);
http_response_code(200);
// process $event['event'] and $event['data'], skipping $event['id'] values already handled

#Retries

A failed attempt is retried on this schedule:

After the sixth failure (about 14.5 hours after the event) that delivery is given up. Other deliveries to the same endpoint carry on independently; an endpoint is never switched off for failing.

Deliveries still waiting when their endpoint is turned off (a platform's endpoints for a company are, when the company revokes the platform) or, for a platform-wide subscription, when the company no longer grants the platform webhooks, are dropped: never sent, marked failed with lastError endpoint inactive or grant revoked and attempts unchanged. platform.grant.* events still go out.

Every attempt is in the endpoint's delivery log (status code, error, next try), and any delivery can be sent again once your server is fixed.

If your endpoint was down longer than that, reconcile from the API: the office schedule shows every job as it is now.

#Ordering and duplicates

• Duplicates happen. If your server handled an event but the answer didn't reach CrewLink (a timeout, a dropped connection), the same delivery comes again with the same id. Store processed ids and skip repeats.
• Order isn't guaranteed. Deliveries go out oldest first, but a retry can land after a newer event: a booking.rescheduled can arrive before the booking.created it follows if the first attempt of booking.created failed. Use createdAt to order events about the same booking, and ignore an event older than the last one you applied.
• Events are notifications, not a log you replay. When you need the current truth (for example after an outage), read it from the API.
• One event per endpoint. Two endpoints subscribed to the same event each get their own delivery with their own id.

#Events

Integrators' ids. Every event about a job (booking.* with bookingId, job.*, attachment.uploaded, request.created, ...) also carries externalRef, externalSource (the job's primary external id, or null) and externalRefs (all of them, { "<source>": "<id>" }, empty when none). See platforms.md.

Sites. Every event about a job (a visit) also carries siteId: the site, the property for its client company with every visit ever made there, it belongs to (null only for one not linked yet, such as a hold). The visit's own fields keep their meaning.

Platforms. A platform can keep one subscription that gets the events of every company that granted it the webhooks scope; companyId in the body says which. See platforms.md.

Events go to the company whose schedule changed. In CrewConnect, a job a sender passes to a partner is on the partner's schedule, so the partner gets its booking.created, stage and payment events; the sender gets the connection.* events addressed to it. Times in data follow the usual conventions: start is an instant, local and from are the wall clock where the job is (booking events carry its zone in timezone: the branch's, which is the company's unless the branch has its own).

#Booking events

booking.created, booking.rescheduled and booking.cancelled share one shape. Every one carries these fields, read from the booking as it is after the change:

Some sources add fields, listed with each event.

#booking.created

A job was booked.

office and api add history: true too when POST /v1/office/jobs writes a past start as history (allowPast).

shareLinkId and bookedBy (every job event, added 2026-10-13). Every event about a job (booking.*, request.created, job.*, attachment.uploaded and the rest that carry jobId or requestId) also carries shareLinkId (the client share link it was booked or requested through) and bookedBy ({ "repName": "Rita Rep", "repEmail": "rita@globex.example" }, the client's sales rep who used it). Both are null for every other job. They are additive: nothing else changed.

{
  "id": 58213,
  "event": "booking.created",
  "createdAt": "2026-10-12T15:30:00.000Z",
  "data": {
    "bookingId": 1042,
    "jobId": 1042,
    "source": "booking_page",
    "status": "booked",
    "serviceId": 2,
    "service": "Repair visit",
    "start": "2026-10-13T19:30:00.000Z",
    "local": "2026-10-13T14:30",
    "end": "2026-10-13T21:00:00.000Z",
    "localEnd": "2026-10-13T16:00",
    "timezone": "America/Chicago",
    "techs": [3],
    "clientCompanyId": null,
    "client": null,
    "externalRef": null,
    "externalSource": null,
    "externalRefs": {},
    "siteId": 311,
    "shareLinkId": null,
    "bookedBy": null
  }
}

The same booking made by a client's rep through a share link:

{
  "event": "booking.created",
  "data": {
    "bookingId": 1043,
    "jobId": 1043,
    "source": "share_link",
    "status": "booked",
    "service": "Site survey",
    "clientCompanyId": "7d0c4c1e-2b7a-4b8e-9a51-3f1f8a2c6b90",
    "client": { "id": "7d0c4c1e-2b7a-4b8e-9a51-3f1f8a2c6b90", "name": "Globex Solar" },
    "shareLinkId": "c1a5e7f2-9b3d-4c8e-a6f0-2d4b8e1c7a93",
    "bookedBy": { "repName": "Rita Rep", "repEmail": "rita@globex.example" }
  }
}

A trip also sends trip.booked with all its stops.

#booking.rescheduled

A booking moved to another time or tech. from is the old local start when there was one.

{
  "id": 58240,
  "event": "booking.rescheduled",
  "createdAt": "2026-10-12T16:02:11.000Z",
  "data": {
    "bookingId": 1042,
    "jobId": 1042,
    "source": "customer",
    "status": "booked",
    "serviceId": 2,
    "service": "Repair visit",
    "start": "2026-10-15T14:00:00.000Z",
    "local": "2026-10-15T09:00",
    "end": "2026-10-15T15:30:00.000Z",
    "localEnd": "2026-10-15T10:30",
    "timezone": "America/Chicago",
    "techs": [5],
    "clientCompanyId": null,
    "client": null,
    "externalRef": null,
    "externalSource": null,
    "externalRefs": {},
    "from": "2026-10-13T14:30"
  }
}

#booking.cancelled

{
  "id": 58251,
  "event": "booking.cancelled",
  "createdAt": "2026-10-12T17:45:00.000Z",
  "data": { "bookingId": 1042, "jobId": 1042, "source": "office", "status": "cancelled", "serviceId": 2, "service": "Repair visit", "start": "2026-10-15T14:00:00.000Z", "local": "2026-10-15T09:00", "end": "2026-10-15T15:30:00.000Z", "localEnd": "2026-10-15T10:30", "timezone": "America/Chicago", "techs": [5], "clientCompanyId": null, "client": null, "externalRef": null, "externalSource": null, "externalRefs": {}, "reason": "Customer called to cancel" }
}

#History emissions (opt-in: historyEvents)

Some events describe the past, or a change a receiver may not want to tell anyone about: a time that has already passed written as history, a job taken off its techs, and a completion that deliberately sent the customer nothing. An integration that turns every booking.rescheduled into a "your appointment moved" message would otherwise send one about a visit that already happened. So these four go only to endpoints that opted in with historyEvents: true:

• historyEvents is false by default: for every endpoint that existed before it was added, and for new ones unless you send historyEvents: true when you subscribe (or POST /v1/platform/webhooks). Turn it on or off with PATCH /v1/office/webhooks/{id} or PATCH /v1/platform/webhooks/{id}. Lists show it.
• With it off, those four are simply not queued for that endpoint (nothing in its delivery log). Every other event, including ordinary booking.created, booking.rescheduled and job.completed (silent: false), is sent as before.
• With it on, the payloads are exactly as documented here (history, unassigned, silent included). Use those fields to decide what, if anything, to tell your users: a history: true event is about a time that has already passed.
• The job's own timeline in CrewLink records these changes either way.

#What each office path sends

notify: false (and a job whose homeowner texts are off) and silent: true only control what reaches the homeowner; they never stop a webhook. The exceptions are the needs-attention flags a double-booking and a job not closed out add, which are written quietly with notify: false (no job.needs_attention). Every event about a job carries its techs where the event has them.

Rows marked historyEvents reach only endpoints with historyEvents: true; every other row reaches every endpoint subscribed to the event.

#block.created

Time off, training or another block on a tech's calendar. Nothing new is offered inside it; jobs already booked there are listed in conflicts for the office to move.

{ "id": 58260, "event": "block.created", "createdAt": "2026-10-12T15:31:00.000Z", "data": { "id": 17, "personId": 3, "start": "2026-10-14T08:00", "end": "2026-10-14T17:00", "timezone": "America/Chicago", "reason": "Training", "conflicts": [1042], "externalRefs": {}, "source": "office", "platform": null, "forced": false } }

#block.deleted

id, personId, externalRefs (the block's), blockSource (office for blocks made through the API or the app, google or outlook for calendar busy time), and source, platform, forced (who removed it).

{ "id": 58261, "event": "block.deleted", "createdAt": "2026-10-12T15:40:00.000Z", "data": { "id": 17, "personId": 3, "externalRefs": { "acme": "pto-9" }, "blockSource": "office", "source": "platform", "platform": "acme", "forced": false } }

#job.en_route, job.arrived, job.completed

The tech moved the job to the next stage in the field app (or, for job.completed, the office or an integration completed it). The three events share one shape:

{ "id": 58301, "event": "job.completed", "createdAt": "2026-10-13T21:12:00.000Z", "companyId": "8a1f0c3e-2b4d-4e6f-9a8b-7c6d5e4f3a2b", "data": { "source": "field_app", "silent": false, "jobId": 1042, "personId": 3, "at": "2026-10-13T21:12:00.000Z", "etaMinutes": null, "minutesOnSite": 94, "externalRef": null, "externalSource": null, "externalRefs": {} } }

#job.running_late

The tech said the current job will run long. CrewLink extended it and handled every later job of the tech's day right away: kept it if it still fits, handed it to a teammate at the same time, moved it to the nearest open time, or (when none was found) texted the homeowner a choice of times. Each homeowner whose job changed was texted, and each job that changed also sends a booking.rescheduled with source running_late.

{
  "id": 58288,
  "event": "job.running_late",
  "createdAt": "2026-10-13T17:05:00.000Z",
  "data": {
    "jobId": 1040,
    "personId": 3,
    "extraMinutes": 45,
    "newEnd": "2026-10-13T13:15",
    "changes": [
      { "jobId": 1042, "action": "handed_off", "local": "2026-10-13T14:30", "techs": ["James"] },
      { "jobId": 1051, "action": "kept", "local": "2026-10-13T16:30", "techs": ["Maria"] }
    ]
  }
}

#job.risk_changed

A stop's risk level changed. CrewLink reads each subscribed company's dispatch board for today every minute and sends one event per stop (per tech, for a crew job) whose level moved since the last one sent; a stop never sent before counts as on_time. The levels, bases and reasons are those of the board's stops[].risk (platforms.md).

Plus externalRef, externalSource, externalRefs like every job event.

{
  "id": 61944,
  "event": "job.risk_changed",
  "createdAt": "2026-10-12T15:30:00.000Z",
  "companyId": "8a1f0c3e-2b4d-4e6f-9a8b-7c6d5e4f3a2b",
  "data": { "jobId": 1190, "personId": 2, "before": "on_time", "after": "late", "reason": "not_started", "basis": "live", "start": "2026-10-12T15:45:00.000Z", "eta": "2026-10-12T16:48:00.000Z", "minutesLate": 63, "externalRef": "appt_88214", "externalSource": "acme", "externalRefs": { "acme": "appt_88214" } }
}

#dispatch.position

A tech's position and field status, for a live map. At most one per tech per 60 seconds, and only when the tech has moved 100 m or more since the last one sent, or their status changed. Only while the tech is on the clock (30 minutes before their first working window or visit of the day to 30 minutes after their last); never off-shift. Sent after a fix from the field app or an On the way / Arrived / Done tap.

Subscribe to it by name: a * subscription doesn't get it (it is the one high-volume event). A platform's endpoints get it by the platform's position rule: a grant with peopleNames: "full" whenever the company's endpoints do; any other grant only while the tech is working a job (platforms.md).

{
  "id": 61950,
  "event": "dispatch.position",
  "createdAt": "2026-10-12T15:29:10.000Z",
  "companyId": "8a1f0c3e-2b4d-4e6f-9a8b-7c6d5e4f3a2b",
  "data": { "personId": 1, "externalRefs": { "acme": "tech_42" }, "status": "en_route", "previousStatus": "idle", "currentJobId": null, "nextJobId": 1188, "position": { "lat": 41.958, "lng": -87.688, "accuracy": 8, "heading": 90, "speed": 12, "recordedAt": "2026-10-12T15:29:00.000Z" } }
}

CrewLink keeps a tech's last known position for 30 days, and a thinned trail of on-the-clock fixes for the company's locationRetentionDays (default 90; platforms.md).

#deposit.paid

{ "id": 58215, "event": "deposit.paid", "createdAt": "2026-10-12T15:33:40.000Z", "data": { "jobId": 1042, "amountCents": 4900 } }

The amount is in the service's currency. The homeowner also gets a receipt text.

#invoice.paid

{ "id": 58330, "event": "invoice.paid", "createdAt": "2026-10-14T02:10:00.000Z", "data": { "invoiceId": 77, "jobId": 1042, "amountCents": 9572 } }

#review.created

{ "id": 58340, "event": "review.created", "createdAt": "2026-10-14T00:02:00.000Z", "data": { "jobId": 1042, "rating": 5 } }

Read the comment with GET /v1/office/reviews.

#request.created

{ "id": 58270, "event": "request.created", "createdAt": "2026-10-12T18:20:00.000Z", "data": { "requestId": 1043, "service": "Repair visit", "requested": [ { "date": "2026-10-20", "part": "morning" }, { "date": "2026-10-21", "part": "any" } ], "source": "client", "client": { "id": "9b1e6f2a-4c3d-4e8f-a7b6-2d1c0e9f8a75", "name": "Globex Solar" }, "filedBy": { "userId": "5c2d9e1f-7a4b-4c8d-9e0f-1a2b3c4d5e6f", "name": "Dana One" } } }

{ "id": 58271, "event": "request.created", "createdAt": "2026-10-12T18:21:00.000Z", "data": { "requestId": 1051, "service": "Repair visit", "queued": true, "reason": "That time was taken when the customer asked for it.", "source": "booking_page", "start": "2026-10-13T19:30:00.000Z", "local": "2026-10-13T14:30", "requested": null } }

When the office places a queued request, booking.created follows with the same id (bookingId).

#trip.booked

The office booked a trip: one tech travels to serve waiting out-of-area requests. Every stop is now booked and each homeowner was texted their time.

{ "id": 58400, "event": "trip.booked", "createdAt": "2026-10-15T14:00:00.000Z", "data": { "tripId": "9a3d7c1e-4b2f-4e8a-b6c5-0d1e2f3a4b5c", "personId": 6, "firstDay": "2026-10-20", "lastDay": "2026-10-21", "jobs": [1043, 1047, 1049] } }

Each stop also sends its own booking.created with source trip and the tripId. If any in-area jobs were handed to teammates to free the trip days, each comes as a booking.rescheduled with source trip_handoff.

#day.reviewed

A day's plan was compared with what happened in the field: every night from 3:00 AM company time for the day before (once per day), and whenever the office asks for a review (POST /v1/office/brain/review). The numbers are the same as Plan vs actual; fetch GET /v1/office/brain/day for the stop-by-stop detail. A day can be reviewed more than once (on request during the day, then at night): keep the latest by computedAt, and treat complete: true as final.

{
  "id": 58512,
  "event": "day.reviewed",
  "createdAt": "2026-10-13T08:10:00.000Z",
  "data": {
    "date": "2026-10-12",
    "computedAt": "2026-10-13T08:10:00.000Z",
    "complete": true,
    "onTimeRate": 92.3,
    "etaMaeOurs": 6.1,
    "etaMaeProvider": 8.4,
    "paired": { "n": 21, "ours": 6.0, "provider": 8.4 },
    "driveErrMean": 2.2,
    "onsiteErrMean": 4.5,
    "counts": { "plannedStops": 26, "arrivals": 26, "done": 25, "drives": 24, "drivesMeasured": 23, "providerLookups": 21, "paired": 21, "checkins": 9, "replans": 5, "customersMoved": 2, "snapshots": 6 }
  }
}

#badge.earned

A tech reached a new tier of a badge (Wins): on the arrived or done tap, or the review, that got them there, or in the nightly recompute. Each person, badge and tier is sent once. Tiers reached from history before Wins existed are not sent.

{
  "id": 58600,
  "event": "badge.earned",
  "createdAt": "2026-10-12T16:52:00.000Z",
  "data": { "personId": 12, "badge": "clockwork", "badgeName": "Clockwork", "tier": "silver", "threshold": 25, "value": 25, "earnedAt": "2026-10-12T16:52:00.000Z" }
}

#connection.requested

Sent to the company being asked.

{ "id": 58500, "event": "connection.requested", "createdAt": "2026-10-12T19:00:00.000Z", "data": { "connectionId": "0b6e4a1c-2f3d-4e5a-8b9c-1d2e3f4a5b6c", "from": "Lakeside Comfort" } }

#connection.accepted

Sent to the company that asked.

{ "id": 58501, "event": "connection.accepted", "createdAt": "2026-10-12T19:20:00.000Z", "data": { "connectionId": "0b6e4a1c-2f3d-4e5a-8b9c-1d2e3f4a5b6c", "partner": "Northline Heating & Air" } }

#connection.ended

Sent to the other side.

{ "id": 58502, "event": "connection.ended", "createdAt": "2026-11-02T09:00:00.000Z", "data": { "connectionId": "0b6e4a1c-2f3d-4e5a-8b9c-1d2e3f4a5b6c", "by": "Lakeside Comfort" } }

See CrewConnect for what each side can see and do.

#message.posted

A person posted a message in Messaging: the company channel, a job thread, a tech's office line, or a CrewConnect partner channel. Direct messages are never sent, and neither are the quiet system messages CrewLink writes into job threads (those mirror the booking and job events above). A job thread or partner channel shared with a CrewConnect partner sends the event to both companies; each sees the sender's name as their app shows it (sender.userId is null and the name reads "First (Company)" for someone at the other company, or "<Company> tech" for a partner's tech when the partner shares open times only).

{ "id": 58530, "event": "message.posted", "createdAt": "2026-10-12T15:42:00.000Z", "data": { "messageId": 812, "conversationId": "7b1d0c52-0e44-4b61-9a3e-5d2f1c9e8a10", "conversationKind": "job", "jobId": 1042, "sender": { "userId": "3f6a9e1c-8d2b-4c7e-a1f0-9b8c7d6e5f40", "name": "Dana Ruiz" }, "body": "Side gate code is 4411", "attachments": 0, "createdAt": "2026-10-12T15:42:00.000Z" } }

#job.needs_attention

Someone flagged the job with POST /v1/office/jobs/{id}/attention, or CrewLink did: a tech's office-review check-in, a customer text that failed, a recurring visit out of the service area, or a job not closed out (still not marked done 3 hours after its scheduled end, or by 21:00 its day: reason Not closed out: still <stage> since <time>, source: "system", by: "closeout", once per job; see office.md). Clearing the flag sends nothing.

{ "id": 58350, "event": "job.needs_attention", "createdAt": "2026-11-02T18:04:00.000Z", "companyId": "8a1f0c3e-2b4d-4e6f-9a8b-7c6d5e4f3a2b", "data": { "jobId": 1042, "reason": "Roof access unclear", "at": "2026-11-02T18:04:00.000Z", "source": "api", "by": "acme", "externalRef": "appt_88213", "externalSource": "acme", "externalRefs": { "acme": "appt_88213" } } }

#attachment.uploaded

A file was added to a job (once per file: after a confirmed upload URL, or a direct upload).

{ "id": 58351, "event": "attachment.uploaded", "createdAt": "2026-11-02T18:05:00.000Z", "companyId": "8a1f0c3e-2b4d-4e6f-9a8b-7c6d5e4f3a2b", "data": { "jobId": 1042, "attachment": { "id": "c0f7a1d2-5b3e-4f6a-8c9d-0e1f2a3b4c5d", "kind": "proposal", "name": "Proposal - Quinn.pdf", "contentType": "application/pdf", "bytes": 482113 }, "uploadedBy": { "kind": "platform", "id": "6d0c1f9a-3b2e-4c55-8f71-0a9b8c7d6e5f", "platform": "acme" }, "at": "2026-11-02T18:05:00.000Z", "externalRef": "appt_88213", "externalSource": "acme", "externalRefs": { "acme": "appt_88213" } } }

uploadedBy.kind is platform, user or company (the company API key). Fetch the file (and a fresh download link) with GET /v1/office/jobs/{id}/attachments.

#person.updated, availability.updated, person.base.updated

About the techs on the team, so an integration can mirror them. Techs appear as first name and last initial (displayName).

{ "id": 58360, "event": "availability.updated", "createdAt": "2026-11-02T18:10:00.000Z", "companyId": "8a1f0c3e-2b4d-4e6f-9a8b-7c6d5e4f3a2b", "data": { "personId": 57, "externalRefs": { "acme": "tech_42" }, "availability": [[[480, 720], [780, 1020]], [[480, 1020]], [[480, 1020]], [[480, 1020]], [[480, 960]], [], []], "hours": [[480, 1020], [480, 1020], [480, 1020], [480, 1020], [480, 960], null, null], "timezone": "America/Chicago", "source": "platform", "platform": "acme", "forced": false } }

#Who made a change: source, platform, forced

block.created, block.deleted, person.updated, availability.updated and person.base.updated say who made the change, so an integration that writes these itself can skip its own echoes:

An integration ignores events with source: "platform" and its own slug in platform, and applies the rest (platforms.md). Events about the same person can arrive out of order: read the person (GET /v1/office/team/{id}) rather than applying an older event over a newer one.

#platform.grant.created, platform.grant.revoked

Only to a platform's platform-wide subscription: a company granted the platform access (or revoked it). data: platform (slug), company (id, slug, name, timezone), scopes, grantedAt, revokedAt (null on created). After a revoke the subscription gets nothing more about that company. Example in platforms.md.

#site.created, site.updated, site.merged

About a site: one property for one client company (or the company's own work), with every visit ever made there. They go out in the same transaction as the visit event that caused them, just before it: a first booking at a property sends site.created then booking.created; finishing the last visit to do sends site.updated (status: "idle") then job.completed; flagging a visit for attention at an idle site sends site.updated (active) then job.needs_attention. An endpoint subscribed to * gets them too (new events always join *): ignore what you don't use. An opt-in emission's site events (a history write: historyEvents) are opt-in the same way.

Every one has the same data, the site as it is after the change. No customer or tech names.

{
  "id": 61022,
  "event": "site.updated",
  "createdAt": "2026-10-14T17:02:00.000Z",
  "companyId": "8a1f0c3e-2b4d-4e6f-9a8b-7c6d5e4f3a2b",
  "data": {
    "siteId": 482,
    "status": "idle",
    "previousStatus": "active",
    "clientCompanyId": "57f617f7-5592-4ba9-a012-6efaaba60677",
    "mergedIntoId": null,
    "externalRefs": { "acme": "job_7731" },
    "firstFiledAt": "2026-10-01T15:02:11.000Z",
    "jobIds": [9104, 9120, 9188],
    "visits": [
      { "jobId": 9104, "visit": 1, "service": "Residential Solar Site Survey", "serviceId": 1, "revisit": false, "status": "cancelled", "stage": "scheduled" },
      { "jobId": 9120, "visit": 2, "service": "Residential Solar Site Survey", "serviceId": 1, "revisit": false, "status": "booked", "stage": "done" },
      { "jobId": 9188, "visit": 3, "service": "Residential Survey Revisit", "serviceId": 3, "revisit": true, "status": "booked", "stage": "done" }
    ],
    "counts": { "visits": 3, "active": 0, "done": 2, "cancelled": 1 },
    "lastVisit": { "jobId": 9188, "at": "2026-10-14T17:02:00.000Z", "service": "Residential Survey Revisit" },
    "nextVisit": null
  }
}

The backfill that places visits booked before sites existed (and regroups after a rule change) sends none of these.

#external_message.created, .updated, .deleted

Only to the endpoints of the platform that owns a job's mirrored conversation (its platform-wide subscription or a company-level endpoint it made), while the company's grant includes webhooks; never to the company's own endpoints or another platform's, even with *. Sent when an office user (or the company API key) answers in the job's Conversations tab, and when the author edits (.updated) or deletes (.deleted) that answer. Only to endpoints whose events list names the event or * (a PATCH of events applies to the next one). data: id (CrewLink's message id), source (crewlink_office), channel (client, tech or internal), jobId, siteId, clientCompanyId, externalRef, externalSource, externalRefs, caseRef (the platform's job or case id), threadKey (null), author (userId, personId, displayName as the grant's people names say, role), body (Markdown; empty on .deleted), attachments (empty), createdAt, editedAt, deletedAt. Messages the platform mirrors in never produce them. Example in platforms.md.

#Testing locally

CrewLink only delivers to public https hosts, so it can't reach localhost directly. Two ways to test:

Tunnel to your machine. Run your handler locally and expose it with a tunnel that gives you a public https host name (for example cloudflared tunnel --url http://localhost:3000 or ngrok http 3000). Subscribe that URL in your sandbox company, then make something happen: book through the booking page, or add a block with POST /v1/office/blocks (a quick way to get block.created). Delete the endpoint when you're done.

Sign a request yourself. To test your verification code without CrewLink, build a signed request the same way CrewLink does:

SECRET='whsec_test_secret'
BODY='{"id":1,"event":"booking.created","createdAt":"2026-10-12T15:30:00.000Z","data":{"bookingId":1042,"source":"booking_page","serviceId":2,"start":"2026-10-13T19:30:00.000Z","local":"2026-10-13T14:30","techs":[3]}}'
T=$(date +%s)
SIG=$(printf '%s.%s' "$T" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | sed 's/^.* //')
curl -X POST http://localhost:3000/crewlink \
  -H 'content-type: application/json' \
  -H 'crewlink-event: booking.created' -H 'crewlink-delivery: 1' \
  -H "crewlink-signature: t=$T,v1=$SIG" \
  --data-binary "$BODY"

Change one character of BODY after signing and your handler should refuse it.