Connect Crisphive to Pipedream

By the end of this guide a Pipedream workflow can book and confirm a field job in Crisphive in one step, look up a caller by phone, and start automatically — with a verified signature — when a job is completed or a customer is created.

Pipedream runs workflows: a trigger starts them and steps do the work, either ready-made actions or short Node.js code. Crisphive is a field operations platform that schedules your technicians with constraint-based scheduling on a deterministic solver.

Three words you will meet below, in plain language: an API key is a long password that lets a program act for your business in Crisphive. A webhook is Crisphive calling a web address when something happens, so your workflow hears about it instantly. An HTTP request is a program calling a web address to read or change something — here, Pipedream calling Crisphive.

This guide uses Pipedream’s built-in HTTP / Webhook trigger, HTTP request and Node.js steps, calling the Crisphive public API directly.

What you can do

Before you start

• A Crisphive account with Developer access — by default only the business Owner has it. It is needed to create API keys, including one with the trigger scopes.
• An existing Pipedream account that can create workflows (see the note above about new sign-ups).
• Every job type you will book has a default duration (Crisphive → Settings → Job Types). The built-in “General” type already has one (60 minutes) and is used when you do not choose a type.
• About 20 minutes for the booking action, 15 more for the trigger. No programming experience is needed: every piece of code below is copy-and-paste.

Step 1 — Create a Crisphive API key

Start with a test key (it begins with chsk_test_). It works only on your business’s Rehearsal copy — the sandbox, with test data — so nothing you do reaches a real customer or technician.

Step 2 — Store the key in Pipedream

Keep the key out of your workflow steps by saving it as a Pipedream environment variable — a named secret every step can read as process.env.FIELD_OPS_API_KEY, or as {{process.env.FIELD_OPS_API_KEY}} in a form field.

Step 3 — Book and confirm a job

Add a step to your workflow after its trigger (a form submission, a new spreadsheet row, a phone-system event…). You can build the request with Pipedream’s HTTP request form (option A) or paste a Node.js step (option B). Both send the same call.

Option A — HTTP request form.

The body, ready to copy:

{
  "customer": {
    "full_name": "Alex Martin",
    "phone": "+16135550177",
    "email": "alex.martin@example.com"
  },
  "address": {
    "line": "145 Laurier Avenue West",
    "city": "Ottawa",
    "state": "ON",
    "postal_code": "K1P 5J3",
    "country": "CA"
  },
  "scheduled_at": "2026-10-06T10:00:00",
  "description": "Furnace stopped heating"
}

A successful answer:

{
  "error_code": 0,
  "message": "Success",
  "data": {
    "job_id": "7b2f0c1e-3a44-4d1b-9a5e-0e6f1c2d3b4a",
    "short_code": "REQ-CA-YCNFQUUV",
    "customer_id": "c4d1a9e2-8f3b-4c6d-a1e2-5f7b9c0d1e2f",
    "confirmed": true,
    "scheduled_at": "2026-10-06T14:00:00Z",
    "assigned_technician_id": "1e9d7c5b-3a2f-4e1d-8c7b-6a5f4e3d2c1b"
  }
}

• error_code 0 means success; anything else is a stable error code (see Troubleshooting).
• scheduled_at in the answer is UTC — 14:00 UTC is 10:00 in Ottawa in October.
• If data.confirmed is false, the job was saved but no technician can take it at that time. data.refusal.error_code says why (for example JOB_REQUEST_NO_TECHNICIAN_AVAILABLE), and the job waits in the coordinator’s queue. Notify a person; do not send the booking again.

Option B — Node.js step. Add a Node.js code step and paste:

export default defineComponent({
  async run({ steps, $ }) {
    // Replace these with data from your trigger, e.g. steps.trigger.event.body.phone
    const booking = {
      customer: {
        full_name: "Alex Martin",
        phone: "+16135550177",
        email: "alex.martin@example.com",
      },
      address: {
        line: "145 Laurier Avenue West",
        city: "Ottawa",
        state: "ON",
        postal_code: "K1P 5J3",
        country: "CA",
      },
      scheduled_at: "2026-10-06T10:00:00", // business local time, no offset
      description: "Furnace stopped heating",
    };

    const res = await fetch("https://api.crisphive.com/v1/job-requests/book-and-confirm", {
      method: "POST",
      headers: {
        Authorization: "Bearer " + process.env.FIELD_OPS_API_KEY,
        "Content-Type": "application/json",
        // Same event => same key => a retry never books twice.
        "Idempotency-Key": "pd-" + steps.trigger.context.id + "-book",
      },
      body: JSON.stringify(booking),
    });
    const envelope = await res.json();
    if (envelope.error_code !== 0) {
      throw new Error("Crisphive " + envelope.error_code + ": " + envelope.message);
    }
    const job = envelope.data;
    $.export("$summary", job.confirmed
      ? "Booked " + job.short_code
      : "Saved " + job.short_code + " — not yet scheduled (" + job.refusal?.error_code + ")");
    return job;
  },
});

Step 4 — Find a customer by phone

Step 5 — Start a workflow on a Crisphive event

Here you create a workflow with an HTTP address, tell Crisphive to call that address on the events you choose, and add a step that checks every call really comes from Crisphive.

Subscribe from a terminal (replace the URL and key):

curl -X POST "https://api.crisphive.com/v1/webhooks" \
  -H "Authorization: Bearer chsk_test_4eC8xQ9mZ2pL7Ka0rT" \
  -H "Idempotency-Key: pipedream-subscribe-2026-10-04" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://eo1234567890abc.m.pipedream.net",
    "event_types": ["job_request.completed", "customer.created"],
    "description": "Pipedream workflow",
    "expires_in_days": 365
  }'

Or from a Node.js step you run once with Test (then delete the step):

export default defineComponent({
  async run({ $ }) {
    const res = await fetch("https://api.crisphive.com/v1/webhooks", {
      method: "POST",
      headers: {
        Authorization: "Bearer " + process.env.FIELD_OPS_API_KEY,
        "Content-Type": "application/json",
        "Idempotency-Key": "pipedream-subscribe-" + Date.now(),
      },
      body: JSON.stringify({
        url: "https://eo1234567890abc.m.pipedream.net", // your trigger URL
        event_types: ["job_request.completed", "customer.created"],
        description: "Pipedream workflow",
        expires_in_days: 365,
      }),
    });
    const envelope = await res.json();
    if (envelope.error_code !== 0) {
      throw new Error("Crisphive " + envelope.error_code + ": " + envelope.message);
    }
    // Copy id and secret now: the secret is never shown again.
    return { id: envelope.data.id, status: envelope.data.status, secret: envelope.data.secret };
  },
});

The verification step (paste as the first Node.js step after the HTTP trigger):

import { createHmac, timingSafeEqual } from "node:crypto";

// Crisphive-Signature: t=<unix seconds>,v1=<hex>[,v1=<hex>]
// v1 = HMAC-SHA256 of "<t>.<raw body>" with the whsec_ secret.
// Accept if ANY v1 matches (two are sent for 24 h after a secret rotation)
// and t is within 5 minutes of now.
function verify(rawBody, header, secret, toleranceSec = 300) {
  if (!header || !secret || rawBody == null) return false;
  let t = "";
  const sigs = [];
  for (const part of String(header).split(",")) {
    const i = part.indexOf("=");
    if (i < 0) continue;
    const k = part.slice(0, i).trim();
    const v = part.slice(i + 1).trim();
    if (k === "t") t = v;
    else if (k === "v1") sigs.push(v);
  }
  const ts = Number(t);
  const now = Math.floor(Date.now() / 1000);
  if (!t || !Number.isFinite(ts) || Math.abs(now - ts) > toleranceSec || sigs.length === 0) return false;
  const body = Buffer.isBuffer(rawBody) ? rawBody : Buffer.from(String(rawBody), "utf8");
  const want = createHmac("sha256", secret).update(t + ".").update(body).digest();
  return sigs.some((s) => {
    const got = Buffer.from(s, "hex");
    return got.length === want.length && timingSafeEqual(got, want);
  });
}

export default defineComponent({
  async run({ steps, $ }) {
    const event = steps.trigger.event;
    const raw = event.bodyRaw ?? (typeof event.body === "string" ? event.body : undefined);
    const body = typeof event.body === "string" ? JSON.parse(event.body) : event.body;

    // The ping arrives while the subscription is being created, before you
    // have the secret. It is never a real event: stop here.
    if (body?.type === "ping") return $.flow.exit("Crisphive ping — nothing to do");

    if (raw === undefined) {
      throw new Error("No raw body: set the HTTP trigger to pass the raw request body");
    }
    const headers = event.headers ?? {};
    const signature = Object.entries(headers)
      .find(([name]) => name.toLowerCase() === "crisphive-signature")?.[1];
    if (!verify(raw, signature, process.env.FIELD_OPS_WEBHOOK_SECRET)) {
      return $.flow.exit("Invalid Crisphive-Signature — ignored");
    }

    // { id, type, created_at, business_id, environment, data: { object } }
    return { event_id: body.id, type: body.type, object: body.data?.object ?? {} };
  },
});

• Job events are thin. A job_request.* event carries the job’s id, short_code and status. Add a GET request to https://api.crisphive.com/v1/job-requests/{{steps.verify.$return_value.object.id}} (replace verify with your step’s name) to read the customer, address, schedule and technician.
• Repeats. Crisphive delivers at least once. Use event_id to skip an event you already handled.
• Events you can subscribe to: GET /v1/webhooks/event-types lists them — job_request.created, .confirmed, .assigned, .rescheduled, .completed, .archived, .status_changed, .priority_changed, customer.created / .updated / .deleted, technician.created / .updated / .deleted.
• Scopes. Subscribing (POST /v1/webhooks) and unsubscribing (DELETE) need developer_manage_api_keys; listing event types needs developer_view. Each event family also needs read access: customer.* needs customers_view, job_request.* needs job_view, technician.* needs team_view; otherwise 403 WEBHOOK_EVENT_NOT_PERMITTED.
• Turning it off. When you no longer need the trigger, call DELETE https://api.crisphive.com/v1/webhooks/{id} with the same key, or delete the endpoint in Crisphive → Settings → Developer → Webhooks. A business can have at most 25 active webhooks per environment.
• Lifetime. With expires_in_days: 365 the secret lasts a year; Crisphive emails the Owner 7 days before. Subscribe again (and store the new secret) before then. A subscription also stops when the key that created it is revoked.

AI agents: Pipedream Connect, MCP and the lasting path

If what you want is an AI assistant that books and manages jobs, you do not need a Pipedream workflow at all. Crisphive runs its own MCP server at https://api.crisphive.com/mcp — MCP (Model Context Protocol) is the standard AI assistants use to discover and call tools. Point any MCP client at it with the header Authorization: Bearer chsk_…, or sign in to Crisphive with OAuth and approve — the connection then acts as the member who approved, with that member’s role. Smaller tool sets: /mcp/voice (caller lookup and one-call booking), /mcp/crm, /mcp/dispatch. See MCP server.

Worked workflows

• Web form → confirmed job. HTTP trigger receiving your form → the Node.js booking step from Step 3 with steps.trigger.event.body fields → if confirmed is true, send the customer an email with short_code; otherwise post “needs a time” to your team chat.
• Caller lookup. Phone-system trigger → Step 4 lookup → if one customer, book with their phone and the address they give; if none, book with full name, phone and address (Crisphive creates the customer).
• Job completed → review request. HTTP trigger subscribed to job_request.completed → verification step → GET the job → email customer.email with your review link.
• New customer → spreadsheet. HTTP trigger subscribed to customer.created → verification step → append object.full_name, object.phone, object.email and event_id to a sheet.

Retries never book twice

The Idempotency-Key header is a label meaning “this is the same request as before”. Built from steps.trigger.context.id (the ID Pipedream gives each incoming event), it stays the same if Pipedream retries the step for that event, and Crisphive replays the first answer instead of booking again. A new event gets a new ID and is a new booking. Never build the key from the current time in a booking step — every retry would then book a second job. Sending the same key with a different body is refused with 422 IDEMPOTENCY_KEY_REUSE.

Test it

Use these fictional details. The 555-01xx range and example.com are reserved for fiction, and Crisphive never texts or emails them.

Troubleshooting

Go live

Related guides and reference

• Automation platforms overview — what every automation integration shares
• n8n — the Crisphive node for self-hosted n8n, plus n8n AI Agents
• Zapier — book jobs from any Zap; instant job and customer triggers
• Make — the same booking and triggers in Make scenarios
• MCP server reference — every tool, the tool profiles and client setup
• Webhooks reference — events, signatures and retries
• Book and confirm a job — the API call behind every booking step