The Couchwork API and webhooks

Overview

Couchwork runs on your own server, so the API lives on your address. In this page we write https://YOUR-SERVER; use the address you sign in to the Couchwork app with (for a box behind a tunnel, that is something like https://acme.example.com). The server needs to be reachable from wherever the calls come from.

• REST and JSON. Everything is under /api/v1. Send and receive JSON.
• Contacts and leads. Create, find, update and move them through your pipelines, and add notes.
• Webhooks. Instead of polling, get a signed message the moment a lead or contact changes.
• Machine-readable. Your server publishes an OpenAPI description at /api/v1/openapi.json, with no key needed. Import it into Postman or generate a client from it.

Quick start

1. Create a key. In the Couchwork app, an admin goes to Settings → Integrations → API keys → Create API key, names it and picks its permissions. Copy the key now: it starts cw_ and is shown only once.
2. Check it works.

   curl https://YOUR-SERVER/api/v1/me \
     -H "Authorization: Bearer cw_…"

   { "name": "Zapier", "scopes": ["contacts:read", "contacts:write", "leads:read", "leads:write"] }

3. Create a lead with its contact in one call:

   curl -X POST https://YOUR-SERVER/api/v1/leads \
     -H "Authorization: Bearer cw_…" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: 3f1d2c4e-0b7a-4a53-9a31-5c2d8e9f1a10" \
     -d '{
       "title": "Website redesign",
       "value": 4000,
       "notes": "Asked for a quote on the contact form",
       "contact": { "firstName": "Sam", "lastName": "Jones", "email": "sam@example.com" }
     }'

   {
     "id": "5d3f6a52-…",
     "title": "Website redesign",
     "value": 4000,
     "notes": "Asked for a quote on the contact form",
     "dueDate": null,
     "pipeline": { "id": "…", "name": "Sales" },
     "stage": { "id": "…", "name": "Lead", "kind": "open" },
     "assignee": null,
     "contact": { "id": "…", "name": "Sam Jones", "email": "sam@example.com", "phone": "", "company": "" },
     "createdAt": "2026-10-17T11:20:00.000Z",
     "updatedAt": "2026-10-17T11:20:00.000Z"
   }

The lead appears on the board straight away, in the first stage of your first pipeline (or in the stage you name with stageId, or the first stage of the pipeline you name with pipelineId), and anything set up to run when a lead enters that stage, such as an automatic email, runs as normal.

Keys and permissions

Send the key on every request as Authorization: Bearer cw_…. Keep it secret, like a password: anyone holding it can do what it is allowed to do. Only a fingerprint is stored on your server, so a lost key can't be shown again. Revoke it in the app and make another.

Give each key only what it needs, and make a separate key for each system so you can revoke one without breaking the others. A key's permissions can't be changed later: revoke it and create another.

How it works

Who owns what a key creates

A key acts as the person who created it. Contacts and leads it creates are owned by them, and the lead's activity says "Lead created via API: Zapier", so your team can see where things came from. Moves, changes and notes are labelled the same way.

Shared contacts only

The API only ever sees shared contacts. Personal contacts are private to their owner: they are not listed, can't be fetched by ID, and don't count when checking for a duplicate email.

Retrying safely (idempotency)

Networks fail, and tools retry. Add an Idempotency-Key header (any unique value, such as a UUID) to creates. If the same key is sent again within 24 hours you get the original answer back, with the header Idempotent-Replayed: true, and nothing is created twice.

Finding and polling

Lists return { "data": [...], "total": 123, "limit": 50, "offset": 0 }. Use limit (1 to 100) and offset to page. To pick up changes, ask for what changed since your last check:

curl "https://YOUR-SERVER/api/v1/leads?updatedSince=2026-10-17T09:00:00Z&order=asc" \
  -H "Authorization: Bearer cw_…"

Where you can, use webhooks instead, so changes arrive the moment they happen.

Mistakes are reported, not ignored

Requests with fields the API doesn't know are refused with a message such as Unrecognized key(s) in object: 'emial', so a typo doesn't silently lose data.

Errors

Errors are JSON, { "error": "What went wrong" }, with a status code:

Limits

At most 120 requests a minute per key. Repeated wrong keys from one address are slowed down too.

Endpoints

This reference is generated from the API's own OpenAPI description. Every path starts with your server address.

Objects

Webhooks

A webhook is Couchwork telling another system that something happened. You give Couchwork an address; when an event you chose occurs, it sends a POST there with the details.

1. In the app: Settings → Integrations → Add webhook. Give it a name, the address to send to, and the events you want (or everything).
2. Copy the signing secret. It is shown once. Your receiver uses it to prove a message really came from your Couchwork.
3. Press Send test. Couchwork sends a webhook.test event straight away and tells you whether your receiver answered.

What arrives

Every message is a POST with a JSON body in this envelope:

{
  "id": "0b6e3a91-…",              // the delivery id: the same on every retry
  "event": "lead.stage_changed",
  "createdAt": "2026-10-17T11:20:00.000Z",
  "data": { … }                     // depends on the event, see below
}

and these headers:

Answer with any 2xx status within 10 seconds. Do slow work after replying.

Retries

If your receiver is down, or answers anything other than 2xx, Couchwork tries again after about 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours: six attempts in all, over roughly 14 hours. Every attempt is recorded under Deliveries for that webhook, where you can also send one again by hand. History is kept for 14 days. Deliveries can arrive out of order, so use the timestamps, not the arrival order.

Where it can send

For safety, addresses must be https:// and must not point at localhost or a private network. If your receiver is on your own network, an admin can switch on Allow addresses on my own network. Redirects aren't followed.

Events

The lead and contact objects are the same ones the API returns (see Objects). Personal contacts, and everyone's private tasks, are never sent. Here is a lead.stage_changed event:

{
  "id": "0b6e3a91-…",
  "event": "lead.stage_changed",
  "createdAt": "2026-10-17T11:20:00.000Z",
  "data": {
    "lead": {
      "id": "5d3f6a52-…", "title": "Website redesign", "value": 4000, "notes": "", "dueDate": null,
      "pipeline": { "id": "…", "name": "Sales" },
      "stage": { "id": "…", "name": "Proposal", "kind": "open" },
      "assignee": { "id": "…", "name": "Priya" },
      "contact": { "id": "…", "name": "Sam Jones", "email": "sam@example.com", "phone": "", "company": "" },
      "createdAt": "2026-10-17T09:02:11.000Z", "updatedAt": "2026-10-17T11:20:00.000Z"
    },
    "from": { "id": "…", "name": "Lead" },
    "to": { "id": "…", "name": "Proposal", "kind": "open" },
    "movedBy": { "id": "…", "name": "Rory" }
  }
}

When a change was made through the API, the actor's name is API: <key name>.

Checking signatures

Anyone who knows your receiver's address could post to it, so check every request really came from your Couchwork. Couchwork-Signature looks like t=1760700000,v1=9c1f…. Work out HMAC-SHA256 of the text <t>.<raw body> using your signing secret, as hex, and compare it to v1 with a constant-time comparison. Use the body exactly as received (before any JSON parsing), and reject messages whose t is more than a few minutes old, which stops replays.

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

export function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const expected = createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  const a = Buffer.from(parts.v1 ?? ''), b = Buffer.from(expected);
  return fresh && a.length === b.length && timingSafeEqual(a, b);
}

import hmac, hashlib, time

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    signed = parts["t"].encode() + b"." + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    fresh = abs(time.time() - int(parts["t"])) < 300
    return fresh and hmac.compare_digest(parts.get("v1", ""), expected)

function verify(string $rawBody, string $header, string $secret): bool {
    parse_str(str_replace(',', '&', $header), $parts);
    $expected = hash_hmac('sha256', $parts['t'] . '.' . $rawBody, $secret);
    $fresh = abs(time() - (int) $parts['t']) < 300;
    return $fresh && hash_equals($expected, $parts['v1'] ?? '');
}

Rotate the secret from the webhook's Edit window if it ever leaks; the old one stops working immediately.

Recipes

Zapier, Make or n8n

• Send Couchwork events to them: create a "Catch Hook" (Zapier) or "Custom webhook" (Make, n8n), paste its address into a new Couchwork webhook, press Send test, then build the rest of the automation.
• Send things into Couchwork: use their "Webhooks / HTTP request" action to POST to /api/v1/leads with your key, as in the quick start. Use the ?upsert=true form of /contacts to keep contacts from duplicating.

Turn a form submission from another site into a lead

Have your form's backend call POST /api/v1/leads with the visitor's details as contact. Use the visitor's submission id as the Idempotency-Key, so a double-click or a retry can't create two leads. (If you only need a simple contact form, Couchwork also has a built-in website form you can paste in with one line.)

Keep another system's customers in sync

Poll GET /api/v1/contacts?updatedSince=… (and /companies) on a schedule, or subscribe to contact.created and contact.updated, and write changes to the other system. Create or update the other direction with POST /api/v1/contacts?upsert=true, using the email as the match.

Changelog

• v1.1: companies. GET/POST /companies, GET/PATCH /companies/:id under the existing contacts permissions, and a companyId on contacts (also in the contact.* webhook payloads). Existing integrations keep working: a contact’s company text is matched to a company automatically.
• v1.0: first release. Contacts and leads, stages and people, API keys with permissions, idempotency, polling, and signed webhooks with retries.