Webhook

Webhook — это механизм, который позволяет сделать POST-запрос на указанный вами URL при возникновении событий отслеживаемого типа на платформе Fasttrack.

Быстрая навигация:

Заполнение формы на сайте
Заполнение форм для бота
Заполнение формы на Landing Page
Смена статусов индивидуальных отправок

Заполнение формы на сайте

Формат уведомления о заполненной веб-форме на сайте:

{
  "event_type": "form_lead_created",
  "payload": {
    "uuid": "00000000-0000-0000-0000-000000000000",
    "form": {
      "uuid": "00000000-0000-0000-0000-000000000000",
      "name": "Название формы"
    },
    "data": {},
    "platform": "Telegram",
    "get_params": {},
    "utm": {},
    "ga_client_id": "751980493.1616501133",
    "created_at": 1621346140426
  },
  "timestamp": 1621346526770
}

Описание параметров события:

event_type — тип события (для этого типа события, он всегда будет иметь единственное значение, равное form_lead_created);
payload — данные о событии;
payload[uuid] — идентификатор данных заполненной формы;
payload[form] — данные о заполненной формы;
payload[form][uuid] — идентификатор данных заполненной формы;
payload[data] — данные формы (содержит объект, где ключ — имя поля формы, а значение — заполненное пользователем значение);
payload[platform] — выбранная пользователем платформа;
payload[get_params] — GET-параметры страницы, на которой пользователь заполнил форму (содержит объект; из этого параметра исключен стандартный набор UTM-меток);
payload[utm] — UTM-метки страницы, где пользователь заполнял форму (содержит объект);
payload[ga_client_id] — уникальный идентификатор посетителя сайта для системы Google Analytics
payload[created_at] — дата и время заполнения формы в формате UNIX Timestamp;
timestamp — дата и время события в формате UNIX Timestamp;

Заполнение форм для бота

Формат уведомления о заполненной веб-форме на сайте:

{
  "event_type": "form_data_created|form_data_updated",
  "payload": {
    "form": {
      "uuid": "0b367f6e-a8ee-402e-80a8-d5ff00e55280",
      "name": "Название формы"
    },
    "chat": {
      "uuid": "236bb7a5-c341-4d3b-86c1-820252c7a60a",
      "platform": "Telegram"
    },
    "data": {
      "field_name": "field_value"
    },
    "created_at": 1623163403290,
    "updated_at": 1629694257394
  },
  "timestamp": 1629694713257
}

Описание параметров события:

event_type — тип события (для этого типа события, он всегда будет одно из двух типов событий form_data_created или form_data_updated);
payload — данные о событии;
payload[uuid] — идентификатор данных заполненной формы;
payload[form] — данные о заполненной формы;
payload[form][uuid] — идентификатор данных заполненной формы;
payload[data] — данные формы (содержит объект, где ключ — имя поля формы, а значение — заполненное пользователем значение);
payload[platform] — выбранная пользователем платформа;
payload[get_params] — GET-параметры страницы, на которой пользователь заполнил форму (содержит объект; из этого параметра исключен стандартный набор UTM-меток);
payload[utm] — UTM-метки страницы, где пользователь заполнял форму (содержит объект);
payload[ga_client_id] — уникальный идентификатор посетителя сайта для системы Google Analytics
payload[created_at] — дата и время заполнения формы в формате UNIX Timestamp;
timestamp — дата и время события в формате UNIX Timestamp;

Заполнение формы на Landing Page

Формат уведомления о заполненной веб-форме на Landing Page:

{
  "event_type": "landing_lead_created",
  "payload": {
    "uuid": "00000000-0000-0000-0000-000000000000",
    "form": {
      "uuid": "00000000-0000-0000-0000-000000000000",
      "name": "Название формы"
    },
    "data": {},
    "platform": "Telegram",
    "get_params": {},
    "utm": {},
    "ga_client_id": "751980493.1616501133",
    "created_at": 1621346140426
  },
  "timestamp": 1621346526770
}

Описание параметров события:

event_type — тип события (для этого типа события, он всегда будет иметь единственное значение, равное landing_lead_created);
payload — данные о событии;
payload[uuid] — идентификатор данных заполненной формы;
payload[form] — данные о заполненной формы;
payload[form][uuid] — идентификатор данных заполненной формы;
payload[data] — данные формы (содержит объект, где ключ — имя поля формы, а значение — заполненное пользователем значение);
payload[platform] — выбранная пользователем платформа;
payload[get_params] — GET-параметры страницы, на которой пользователь заполнил форму (содержит объект; из этого параметра исключен стандартный набор UTM-меток);
payload[utm] — UTM-метки страницы, где пользователь заполнял форму (содержит объект);
payload[ga_client_id] — уникальный идентификатор посетителя сайта для системы Google Analytics
payload[created_at] — дата и время заполнения формы в формате UNIX Timestamp;
timestamp — дата и время события в формате UNIX Timestamp;

Смена статусов индивидуальных отправок

Пример уведомления смене статуса индивидуальной отправки:

{
  "event_type": "push_message",
  "payload": {
    "uuid": "00000000-0000-0000-0000-000000000000",
    "chat": {
      "uuid": "00000000-0000-0000-0000-000000000000",
      "platform": "Telegram"
    },
    "state": {
      "code": "PENDING",
      "detail": "текст"
    },
    "created_at": 1621346140426,
    "sent_at": 1621346140426,
    "delivered_at": 1621346140426
  },
  "timestamp": 1621346140426
}

Описание параметров события:

event_type - тип события (для этого типа события, он всегда будет иметь единственное значение, равное push_message);
payload — данные о событии;
payload[uuid] — идентификатор данных о смене статуса индивидуальной отправки;
payload[chat] — данные о чате;
payload[chat][uuid] — уникальный идентификатор чата на платформе;
payload[chat][platform] — канал, через который подключен чат;
payload[state] — данные о текущем статусе отправки;
payload[state][code] — код статуса отправки;
payload[state][detail] — дополнительная информация о статусе отправки;
payload[created_at] — дата и время создания отправки в формате UNIX Timestamp;
payload[sent_at] — дата и время отправки в формате UNIX Timestamp;
payload[delivered_at] — дата и время смены статуса в формате UNIX Timestamp;
timestamp - дата и время события в формате UNIX Timestamp;

Возможные коды статусов отправки (payload[state][code]) — приведены в таблице ниже:

Название

Описание

PENDING

В ожидании отправки (по умолчанию)

CANCELLED

Отправка отменена пользователем платформы или через API

IN_PROCESS

В процессе отправки

SENT

Отправлено

ERROR

Ошибка отправки

DELIVERED

Доставлено

UNDELIVERED

Не доставлено

Система будет делать POST-запрос, закодированный в application/json, на указанный URL. Для подтверждения, что данные пришли от нас, вы можете воспользоваться функционалом подписи запроса.

Пример формирования такой подписи на языке Python — приведен ниже:

import hashlib
import hmac

def generate_signature_header(url: str, method: str, body: str, sign_key: str) -> str:
    """
    :param url: URL адрес HTTP запроса
    :param method: метод HTTP запроса
    :param body: тело запроса
    :param sign_key: ключ для формирования подписи
    :return: подпись для отправки в заголовке X-Signature
    """
    signature_message = url + method + body
    signature = hmac.new(
        sign_key.encode(),
        signature_message.encode(),
        digestmod=hashlib.sha512,
    )
    header = signature.hexdigest()
    return header

Ключ для формирования подписи настраивается в разделе «Системные настройки»:

Значение подписи будет передано в HTTP-заголовке с названием X-SIGNATURE.

Для подтверждения доставки уведомления необходимо:

Ответить статусом 200 OK в течение 2 секунд;

В случае ошибки и/или отправки другого статуса — запрос будет повторяться еще **5****раз, но задержка между ними каждый раз будет возрастать в два раза: 2, 4, 8, 16, 32 сек.

PreviousWebhook и Web API NextAPI

Last updated 1 month ago