Вебхук приёма лидов — справочник

Обновлено: 11 августа 2026 г.

Когда у платформы форм нет готовой интеграции — самописный сайт, внутренняя система, скрипт бэк-офиса — лиды можно отправлять в КО напрямую. Это коннект Вебхук: прием лидов.

Обязателен только контакт. Всё остальное улучшает то, что смогут показать отчёты.

Запрос

Адрес: https://webhook.kodata.pro/{hash32} — выдаётся в настройках коннекта.

Метод: POST

Тип содержимого: application/json или multipart/form-data

Любое поле можно не передавать, кроме контакта. Телефон принимается в любом виде:

Телефон и почта могут содержать несколько значений — передайте массив.

Минимальный запрос

{
  "contact": {
    "phone": "+358 40 123 4567"
  }
}

Так создаётся лид без источника. В отчётах он будет неразмеченным — и это правильный ответ, когда источник действительно неизвестен. Но если человек пришёл через ваш сайт, передайте идентификатор касания, и лид размеченным быть перестанет.

Минимальный запрос с источником

{
  "contact": {
    "phone": "+358 40 123 4567"
  },
  "touch": {
    "touch_id": 123
  }
}

touch_id берётся из cookie _ko_touch_id, которую счётчик КО выставляет на ваших страницах. Прочитать эту cookie и передать её сюда — и есть вся привязка источника: именно она связывает лид с кампанией, из которой пришёл визит.

Полный запрос

{
  "contact": {
    "name": "Имя Фамилия",
    "phone": "+358 40 123 4567",
    "email": "person@example.com"
  },
  "lead": {
    "amount": 1000,
    "currency": "EUR",
    "profile": {
      "comment": "Перезвоните завтра",
      "i-agree": "on"
    }
  },
  "touch": {
    "touch_id": "123456",
    "communication": "site",
    "action": "lead",
    "site_url": "https://example.com/path?utm_source=newsletter",
    "ref_url": "https://referrer.example/path",
    "user_device": "desktop",
    "user_browser": "firefox",
    "user_ip": "127.0.0.1"
  }
}

Поля контакта принимают и мессенджеры: whatsapp, telegram, viber, facebook, instagram, skype.

lead.profile — собственные поля формы. Либо объект пар имя: значение, либо массив объектов {name, label, value}, когда нужно сохранить и человекочитаемую подпись:

"profile": [
  { "name": "comment", "label": "Комментарий", "value": "Перезвоните завтра" }
]

Значения полей touch:

Значение вне списка КО не отклонит, но и не поймёт: канал и действие участвуют в определении источника, и выдуманное значение уводит лид в «неизвестный» канал.

touch дополнительно принимает UTM-поля (utm_source, utm_medium, utm_campaign, utm_content, utm_term) и идентификаторы посетителя (client_id_ko, client_id_ga, client_id_fb), если они у вас есть.

Ответ

JSON, HTTP 200.

{
  "contact_state": "ok",
  "contact_id": 111,
  "lead_id": 222,
  "crm_service": "HubSpot",
  "crm_contact_id": 333,
  "crm_lead_id": 444
}

Отправка удалась, если contact_id не равен 0. Проверяйте именно его: contact_state и crm_service приходят только тогда, когда лид ушёл в подключённую к проекту CRM, — у проекта без CRM ответ состоит из идентификаторов.

contact_state: "double" означает, что контакт уже есть в КО или в вашей CRM и заново создан не был — возвращается идентификатор существующего. Это нормальный исход, а не ошибка: считайте его успехом.

Ошибки

Ошибка приходит тем же 200 с парой полей вместо идентификаторов:

{
  "error_code": 1,
  "error_message": "putContact: Contact not created. Check request."
}

error_code: 1 — запрос не принят (пустой или неразборный контакт); error_code: 2 — putContact: Ignored by filter, лид отсечён правилом отбора, настроенным в коннекте.

Тестовый режим

Добавьте параметр test, чтобы получить смоделированный ответ, ничего не создавая. Значение определяет числа в ответе, так что тесты можно отличать друг от друга: test=1 возвращает contact_id: 1 и contact_state: "double", test=2 — contact_id: 2 и contact_state: "ok", и так далее.

{
  "test": 2,
  "contact": { "name": "Имя Фамилия", "phone": "+358 40 123 4567" }
}

{
  "contact_state": "ok",
  "contact_id": 2,
  "lead_id": 2,
  "crm_contact_id": 20,
  "crm_lead_id": 20,
  "crm_service": "Test"
}

Чтение статуса лида

По умолчанию выключено — включается в настройках коннекта галочкой Разрешить чтение статуса по лидам; сумма сделки отдаётся отдельной галочкой Показывать сумму сделки.

Если статусы нужны сразу при изменении, а не по запросу, напишите в техподдержку — постбэки (лид создан, лид изменился, сделка успешна, сделка закрыта) настраиваются отдельно и сами приходят на ваш адрес.

Тот же адрес, метод GET или POST. Лиды ищутся по lead_id или по crm_lead_id, не более 100 за запрос. Видны только лиды, отправленные через этот же вебхук; удалённых в ответе нет.

{
  "method": "getLeads",
  "filter": {
    "lead_id": [1, 2]
  }
}

{
  "leads": [
    { "lead_id": 1, "crm_lead_id": 10, "state": "process", "amount": 0, "currency": "" },
    { "lead_id": 2, "crm_lead_id": 20, "state": "success", "amount": 1000, "currency": "EUR" }
  ]
}

state принимает значения process, success, fail. Какие поля вернутся, зависит от разрешений в настройках коннекта: по умолчанию отдаётся только статус, без суммы сделки.