Cotnek API & webhooks

Quick start

1. In Cotnek, open Settings → API & webhooks and click Generate new key. Copy it — it is shown only once. (Owners and admins only.)
2. Call the API with the key in the Authorization header:

curl https://cotnek.com/api/v1/leads \
  -H "Authorization: Bearer ck_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Sara Ahmed","email":"sara@example.com","phone":"+971501234567","source":"Website form"}'

The lead appears in your pipeline and your “new lead” automations run, exactly as if it came from a Cotnek form.

Authentication

Every request needs your workspace key: Authorization: Bearer ck_live_… (or X-Api-Key: ck_live_…). The key acts for your whole workspace, so keep it on a server — never in a web page or app that customers can open. Generating a new key stops the old one at once.

Base URL: https://cotnek.com/api/v1. Requests and responses are JSON.

Leads

Endpoint	What it does
POST /leads	Adds a lead. If a lead with the same email or phone already exists, that lead is updated instead (answer 200 with "created": false), so retries never create duplicates.
GET /leads	Lists leads, newest first. Filters: stage, email, tag, source, updated_since (ISO date). Paging: limit (max 100) and starting_after (a lead id).
GET /leads/{id}	One lead.
PATCH /leads/{id}	Updates name, email, phone, company, value_usd, stage, add_tags, remove_tags, or adds a note. Moving to a stage runs that stage's automations; moving to won records the deal.

Fields for POST /leads: name, email, phone (at least one of these), company, source (defaults to “API”), tags (list), value_usd, notes. Stages: new, contacted, qualified, proposal, negotiation, won, lost.

{
  "data": {
    "id": "6a0f1c2e9b7d4a0012ab34cd",
    "name": "Sara Ahmed",
    "email": "sara@example.com",
    "phone": "+971501234567",
    "company": null,
    "source": "Website form",
    "stage": "new",
    "tags": [],
    "value_usd": 0,
    "created_at": "2026-10-23T09:14:02.511Z",
    "updated_at": "2026-10-23T09:14:02.511Z"
  },
  "created": true
}

Deals & campaigns

Endpoint	What it does
GET /me	Your workspace name and the list of stages — a quick way to test a key.
GET /deals	Won deals (lead_id, amount_usd, won_at). Filter with won_since.
GET /campaigns	Your Meta and Snapchat campaigns with budget, spend and results.

Webhooks

Add a webhook URL in Settings → API & webhooks (it must be a public https:// address). Cotnek then POSTs these events to it:

• lead.created — a new lead from any source (forms, website chat, WhatsApp, Meta Lead Ads, the API…)
• lead.stage_changed — a lead moved stage (includes previous_stage)
• deal.won — a lead moved to won (includes value_usd)

POST https://your-endpoint.example/cotnek
Content-Type: application/json
Cotnek-Event: lead.created
Cotnek-Delivery: 6a0f1c2e9b7d4a0012ab3500
Cotnek-Signature: t=1792746842,v1=5f2c…

{
  "id": "6a0f1c2e9b7d4a0012ab3500",
  "type": "lead.created",
  "created_at": "2026-10-23T09:14:02.700Z",
  "data": { "lead": { "id": "6a0f1c2e9b7d4a0012ab34cd", "name": "Sara Ahmed", "email": "sara@example.com", "stage": "new", "...": "..." } }
}

Answer with any 2xx status within 10 seconds. Anything else is retried after 1 minute, 10 minutes and 1 hour. Every delivery and its result is listed in Settings, and Send a test event sends a sample.

Verify signatures

Check that a request really came from Cotnek: compute HMAC-SHA256 of "{t}.{raw body}" with your signing secret (Settings → API & webhooks) and compare it with v1. Reject requests whose t is more than 5 minutes old.

// Node.js (Express): use the raw body, before any JSON parsing
const crypto = require('crypto');

function fromCotnek(rawBody, header, secret) {
  const [, t, v1] = /^t=(\d+),v1=([a-f0-9]{64})$/.exec(header || '') || [];
  if (!t || Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

Zapier & Make

Get Cotnek events in Zapier

1. Create a Zap with the trigger Webhooks by Zapier → Catch Hook and copy its URL.
2. Paste it as the webhook URL in Cotnek and click Send a test event.
3. Add your action — a Google Sheets row, a Slack message, your accounting tool. Zapier receives every event type; add a Filter step on type to keep only the ones you want.

Send leads to Cotnek from Zapier

Use the action Webhooks by Zapier → POST with URL https://cotnek.com/api/v1/leads, payload type JSON, the fields above as data, and a header Authorization = Bearer ck_live_….

Make (Integromat)

Use Webhooks → Custom webhook to receive Cotnek events, and the HTTP → Make a request module to call the API with the same header.

Errors & limits

Status	Meaning
400	A field is missing or invalid — the message says which.
401	The key is missing, wrong or was replaced.
402	Your plan's limit is reached (for example, number of leads).
404	Not found in your workspace.
429	More than 120 requests a minute — wait and retry.