WebHooks

Общее

Swagger: https://api.radist.online/v2/docs#/Webhooks

Необходимые права доступа (scopes) для работы с API: webhooks

Для получения уведомлений о событиях, происходящих в компании, можно подписаться на вебхуки. Это рекомендуемый способ получения уведомлений.

Подписка на вебхуки

https://api.radist.online/v2/docs#/Webhooks/WebhooksCreateItem

Для подписки на вебхуки необходимо задать адрес, на который они будут приходить, указать, для какого из подключений вы хотите получать вебхуки и указать список типов событий (event_type, описаны ниже), уведомления о которых вам нужны.

Формат вебхука

Общий формат такой:

{
  "company_id": 123,
  "event_type": "string",
  "event": {}
}

Содержимое event зависит от event_type:

event_type=messages.create:

{
  "connection_id": 12345,
  "contact_id": 12345,
  "chat_id": "string",
  "message": {}
}

Схема объекта message (см. модель Message): https://api.radist.online/v2/docs#/model-Message

event_type=messages.delivery.{delivered | read | error}:

{
  "connection_id": 12345,
  "contact_id": 12345,
  "chat_id": "string",
  "message_id": "string",
  "error_type": "GENERIC_ERROR" | "SUBSCRIPTION_NOT_PAID" | "MESSENGER_USER_NOT_FOUND" | "DIALOGS_LIMIT_EXCEEDED" | "WABA_DIALOGS_LIMIT_EXCEEDED" | "CHAT_BLACKLISTED" | null,
  "error_text": "string" | null
}

event_type=connections.status_changed:

// Возможные варианты:
// 1) status_type = good | bad
// 2) status_subtype = | normal (всё в порядке)
//                     | whatsapp_qr_not_scanned (только WhatsApp)
//                     | generic_authorization_error (все остальные)


// Первый логин, предыдущего статуса (old_status) нет
{
  "company_id": 12345,
  "event_type": "connections.status_changed",
  "event": {
    "connection_id": 4567,
    "new_status": {
      "status_type": "good",
      "status_subtype": "normal",
      "created_at": "2025-10-20T11:02:49.887235+00:00",
      "updated_at": "2025-10-20T11:02:49.887235+00:00"
    },
    "old_status": null
  }
}


// Соединение потеряно
{
  "company_id": 12345,
  "event_type": "connections.status_changed",
  "event": {
    "connection_id": 6789,
    "new_status": {
      "status_type": "bad",
      "status_subtype": "generic_authorization_error",
      "created_at": "2025-10-20T10:59:53.658191+00:00",
      "updated_at": "2025-10-20T10:59:53.635477+00:00"
    },
    "old_status": {
      "status_type": "good",
      "status_subtype": "normal",
      "created_at": "2025-10-20T09:47:04.765144+00:00",
      "updated_at": "2025-10-20T10:58:28.882972+00:00"
    }
  }
}

Замечания

• Обрабатывайте вебхуки асинхронно. Сохранили в очередь, ответили, что приняли, и только потом обработали.

• Тело ответа/заголовки ответа игнорируются. Рекомендуем сократить их до минимума.

• На обновление настроек вебхуков может потребоваться до 5 минут. В течение этого времени вебхуки всё ещё могут приходить на ранее указанные адреса.

• Сервер вебхуков ожидает ответ со статусами 200, 201, 202 в течение 5 секунд.

• Если был получен ответ со статусом 4xx, то повторной отправки вебхука не будет.

• Если был получен другой ответ, ответ был не получен за 5 секунд, или произошла другая ошибка (например, недействительный SSL-сертификат) то вебхук будет отправлен повторно с интервалами: 1, 3, 10, 30, 60 минут.

• Если сервер не отвечает или отвечает статусами 5xx дольше 3 часов подряд, отправка вебхуков может быть временно приостановлена или отключена совсем.

Примеры

// Текстовое сообщение (отправитель - пользователь с user_id=96)
{
  "company_id": 510,
  "event_type": "messages.create",
  "event": {
    "connection_id": 6466,
    "contact_id": 1183,
    "chat_id": 452764,
    "chat": {
      "id": 452764,
      "name": "A",
      "is_group": false,
      "phone": "79000000000",
      "username": null,
      "avatar_url": null
    },
    "message": {
      "message_id": "1a1937d6-bf4c-4269-b5a3-7a8c02c3aba2",
      "source_message_id": "[email protected]_CD0E4C02A58334A581CDE1976E952A32",
      "chat_id": "[email protected]",
      "direction": "inbound",
      "message_type": "text",
      "author": {
        "id": "0b4fadf0-76b1-4463-baae-e0c8a091263a",
        "name": "Dmitry V.",
        "external_id": "96",
        "user_id": 96,
        "phone": null
      },
      "created_at": "2024-02-07T13:28:05+00:00",
      "delivered_at": null,
      "read_at": null,
      "error_at": null,
      "text": {
        "text": "6"
      }
    }
  }
}


// Сообщение с файлом (с картинкой)
{
    "company_id": 510,
    "event_type": "messages.create",
    "event": {
        "connection_id": 6466,
        "contact_id": 1183,
        "chat_id": 452764,
        "chat": {
            "id": 452764,
            "name": "A",
            "is_group": false,
            "phone": "79000000000",
            "username": null,
            "avatar_url": null
        },
        "message": {
            "message_id": "0e476e42-014d-499b-9755-c60499884ec6",
            "source_message_id": "[email protected]_06721C8DAA4798EB67A6F8943E273E87",
            "chat_id": "[email protected]",
            "direction": "inbound",
            "message_type": "image",
            "author": null,
            "created_at": "2024-02-07T13:45:20+00:00",
            "delivered_at": null,
            "read_at": null,
            "error_at": null,
            "image": {
                "caption": "Demo",
                "name": "3a5891c7-5c8b-4793-9eff-9f77782e0c07.jpg",
                "size": 73065,
                "mime_type": "image/jpeg",
                "url": "https://example.org/image.jpg"
            }
        }
    }
}


// Сообщение с корзиной waba
{
    "company_id": 12345,
    "event_type": "messages.create",
    "event": {
        "connection_id": 123123,
        "contact_id": 1,
        "chat_id": 186008,
        "chat": {
            "id": 186008,
            "name": "Demo",
            "is_group": false,
            "phone": "79000000000",
            "username": null,
            "avatar_url": "https://example.org/avatar.jpg"
        },
        "message": {
            "message_id": "3a830de8-5b5f-480d-a821-49e9b14f9a7e",
            "source_message_id": "ABGGeRclMZhPAhBMMpdb-YwGu6DPc-XuT08H",
            "chat_id": "79000000000",
            "direction": "inbound",
            "message_type": "waba_order",
            "created_at": "2023-08-25T10:09:53+00:00",
            "delivered_at": null,
            "read_at": null,
            "error_at": null,
            "waba_order": {
                "currency": "RUB",
                "amount": 6000,
                "items": [
                    {
                        "name": "WhatsApp + amoCRM",
                        "price": 3000,
                        "quantity": 1,
                        "image_url": "https://radist2.cdn.radist.online/facebook/products/241352448870357/4y7fbkr62n/image.jpg",
                        "retailer_id": "4y7fbkr62n"
                    },
                    {
                        "name": "Телегомагазин",
                        "price": 1500,
                        "quantity": 2,
                        "image_url": "https://radist2.cdn.radist.online/facebook/products/241352448870357/psgsvcmha7/image.jpg",
                        "retailer_id": "psgsvcmha7"
                    }
                ],
                "comment": "",
                "catalog_id": 241352448870357
            }
        }
    }
}


// Сообщение в групповом чате (chat.is_group=true)
{
  "company_id": 510,
  "event_type": "messages.create",
  "event": {
    "connection_id": 6466,
    "contact_id": 1225,
    "chat_id": 452784,
    "chat": {
      "id": 452784,
      "name": "A",
      "is_group": true,
      "avatar_url": null
    },
    "message": {
      "message_id": "1b92db5f-0214-4641-b524-e5386a964800",
      "source_message_id": "[email protected]_05CFE59C2F17C02ED9EC462A7E561DC3",
      "chat_id": "[email protected]",
      "direction": "inbound",
      "message_type": "text",
      "author": {
        "id": "e6f74a69-c7a9-4b72-ae64-c2d6473b201a",
        "name": "A",
        "external_id": "[email protected]",
        "phone": "[phone]"
      },
      "created_at": "2024-02-07T13:29:23+00:00",
      "delivered_at": null,
      "read_at": null,
      "error_at": null,
      "text": {
        "text": "2"
      }
    }
  }
}



// Сообщение доставлено
{
    "company_id": 12345,
    "event_type": "messages.delivery.delivered",
    "event": {
        "connection_id": 123123,
        "contact_id": 217140,
        "chat_id": 1036686,
        "message_id": "3fe648ad-fbb4-4412-9081-2ee31b02a164"
    }
}

// Сообщение прочитано
{
    "company_id": 12345,
    "event_type": "messages.delivery.read",
    "event": {
        "connection_id": 123123,
        "contact_id": 217140,
        "chat_id": 1036686,
        "message_id": "3fe648ad-fbb4-4412-9081-2ee31b02a164"
    }
}

// Ошибка доставки
{
  "company_id": 12345,
  "event_type": "messages.delivery.error",
  "event": {
    "connection_id": 123123,
    "contact_id": 217140,
    "chat_id": 1036686,
    "message_id": "3fe648ad-fbb4-4412-9081-2ee31b02a164",
    "error_type": "GENERIC_ERROR",
    "error_text": "Re-engagement message\nMessage failed to send because more than 24 hours have passed since the customer last replied to this number."
  }
}