API и вебхуки WorkAB

Ключ

Ключ создаёт владелец компании: Настройки → API и вебхуки → Создать ключ. Ключ показывается один раз — сохраните его. Ключ открывает данные вашей компании, поэтому передавайте его только серверу; в код страниц сайта не вставляйте. Ненужный ключ отзывается там же.

Ключ передаётся заголовком:

Authorization: Bearer wab_ваш_ключ

Если сервис не умеет ставить заголовок (вебхук формы Tilda) — параметром адреса ?key=wab_ваш_ключ.

Адрес API: https://crm.workab.ru/api/v1. Ответы — JSON в UTF-8. Не больше 120 запросов в минуту на ключ.

Методы

Метод	Адрес	Что
GET	/api/v1/projects	Проекты: id, code (номер договора), address, client_id, client_name, status, start_date, created_at
GET	/api/v1/builds	Объекты стройки: id, code, address, client_name, status, contract_sum, start_date, created_at
GET	/api/v1/clients	Заказчики: id, name, org, phone, email, created_at
GET	/api/v1/leads	Лиды: id, code, client_id, client_name, phone, email, source, status, note, created_at
POST	/api/v1/leads	Создать лид: name (обязательно), phone или email, source, note
GET	/api/v1/payments	Поступления: id, kind (project | build), project_id, build_id, date, amount, method, created_at
GET	/api/v1/ks-acts	Утверждённые акты КС-2: id, number, act_date, smeta_id, build_id, amount (без НДС), approved_at

Списки отдаются по времени создания, по 100 записей. Параметры: since — дата и время ISO, вернуть созданные позже; limit — от 1 до 500. Если записей больше, в ответе next_since — передайте его в since следующего запроса.

curl -H "Authorization: Bearer wab_ваш_ключ" "https://crm.workab.ru/api/v1/leads?since=2026-10-01T00:00:00Z&limit=50"

{
  "leads": [
    {
      "id": "6a3f…",
      "code": "Л 15-26",
      "client_id": "91c2…",
      "client_name": "Иванов Пётр",
      "phone": "+7 900 111-22-33",
      "email": null,
      "source": "Tilda",
      "status": "new",
      "note": "Дом 150 м²",
      "created_at": "2026-10-28T09:41:12.000Z"
    }
  ],
  "next_since": null
}

Лид со своего сайта

POST /api/v1/leads — JSON или форма (application/x-www-form-urlencoded). Поля: name — обязательно; phone или email — хотя бы одно; source — откуда (по умолчанию «API»); note — комментарий. Лид появится в разделе «Лиды» с номером и ответственным — владельцем компании.

curl -X POST "https://crm.workab.ru/api/v1/leads" \
  -H "Authorization: Bearer wab_ваш_ключ" -H "Content-Type: application/json" \
  -d '{"name": "Иванов Пётр", "phone": "+7 900 111-22-33", "source": "Сайт", "note": "Дом 150 м²"}'

Ответ — 201 и созданный лид. Ошибки — 400 с текстом в поле error.

Tilda

В Tilda: Настройки сайта → Формы → Webhook, адрес:

https://crm.workab.ru/api/v1/leads?key=wab_ваш_ключ

Поля формы Name, Phone, Email Tilda отправит сама; источник лида — «Tilda», в комментарий попадёт название формы. Проверочный запрос Tilda при подключении получит ответ «ok».

Вебхуки

Вебхук — адрес на вашем сервере, куда WorkAB сам отправляет события. Заводится в Настройки → API и вебхуки: адрес (только https://, во внешней сети) и события. Секрет для проверки подписи показывается один раз. Кнопка «Проверить» отправляет событие ping.

Событие	Когда
lead.created	новый лид
project.created	новый проект
build.created	новый объект стройки
client.created	новый заказчик
payment.created	поступила оплата по проекту или объекту
ks_act.approved	утверждён акт КС-2

События собираются раз в минуту. Запрос — POST с JSON; data — та же запись, что отдаёт API:

{
  "id": "0b7e…",
  "event": "lead.created",
  "created_at": "2026-10-28T09:41:12.000Z",
  "data": {
    "id": "6a3f…",
    "code": "Л 15-26",
    "client_name": "Иванов Пётр",
    "phone": "+7 900 111-22-33",
    "source": "Tilda",
    "status": "new"
  }
}

Заголовки: X-WorkAB-Event — событие, X-WorkAB-Delivery — номер доставки (по нему отсеивайте повторы), X-WorkAB-Signature — sha256= и HMAC-SHA256 тела запроса вашим секретом.

Ответьте кодом 2xx в течение 10 секунд. Иначе WorkAB повторит через 1, 5, 30 минут, 2 и 12 часов; после шестой неудачи событие помечается недоставленным — это видно в настройках.

Проверка подписи

Node.js:

import { createHmac, timingSafeEqual } from 'node:crypto';
// rawBody — тело запроса как есть, до разбора JSON
function подписьВерна(rawBody, заголовок, секрет) {
  const ожидаем = 'sha256=' + createHmac('sha256', секрет).update(rawBody).digest('hex');
  return заголовок.length === ожидаем.length && timingSafeEqual(Buffer.from(заголовок), Buffer.from(ожидаем));
}

PHP:

$body = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $body, $secret);
if (!hash_equals($expected, $_SERVER['HTTP_X_WORKAB_SIGNATURE'] ?? '')) { http_response_code(401); exit; }
$event = json_decode($body, true);

Ошибки

401	нет ключа, ключ неверный или отозван
400	не хватает полей — текст в error
404	нет такого адреса API
429	больше 120 запросов в минуту

Версия API — v1: поля ответов в ней не переименовываются и не удаляются; новые могут добавляться. Вопросы — в «Чат с WorkAB» в кабинете.