Вебхуки: приём запросов в скрипт
Триггер «По вебхуку» даёт скрипту секретный адрес. Внешний сервис (интернет-магазин, CRM, платёжная система, форма на сайте) отправляет на него запрос, Coverse сразу отвечает 200 OK и запускает функцию скрипта с данными запроса.
Здесь речь о входящих запросах в скрипт. Если нужно, наоборот, получать уведомления об изменениях таблицы в своём сервисе, используйте подписки API: пример с уведомлениями в Telegram на портале API.
Создать адрес
- В редакторе скрипта откройте вкладку «Триггеры» → «Добавить триггер» → «По вебхуку».
- Выберите функцию, которую будет вызывать запрос, например
onWebhook. - Скопируйте адрес и вставьте его в настройки внешнего сервиса.
Есть два способа передать секрет:
| Способ | Адрес | Секрет |
|---|---|---|
| Секрет в адресе | https://app.coverse.team/api/hooks/scripts/whs_… | часть адреса |
| Секрет в заголовке | https://app.coverse.team/api/hooks/scripts/<идентификатор триггера> | заголовок X-Coverse-Token: whs_… |
Адреса запросов попадают в журналы серверов по пути, поэтому, если сервис умеет отправлять свои заголовки, выбирайте секрет в заголовке.
Секрет видят только создатель триггера и владелец скрипта. Если секрет мог попасть в чужие руки, нажмите «Перевыпустить секрет»: старый адрес сразу перестанет работать, новый нужно вставить во внешний сервис.
Функция скрипта
function onWebhook(event) {
if (!event) return;
const order = event.json || {};
Coverse.table.getSheet("Заказы").appendRow([
new Date(),
order.id,
order.customer,
Number(order.total),
]);
}
Поля события:
| Поле | Что содержит |
|---|---|
event.json | тело запроса, разобранное из JSON, или null |
event.form | поля формы, если тело в формате application/x-www-form-urlencoded |
event.body | тело запроса текстом |
event.query | параметры адреса (?source=shop) |
event.headers | заголовки запроса |
event.method | метод запроса |
event.contentType | тип содержимого |
event.ip | адрес отправителя |
event.receivedAt | время получения |
Заголовки с учётными данными (Authorization, Cookie, X-Coverse-Token и подобные) в событие не попадают.
Пример запроса
curl -X POST "https://app.coverse.team/api/hooks/scripts/ИДЕНТИФИКАТОР_ТРИГГЕРА" \
-H "X-Coverse-Token: whs_ВАШ_СЕКРЕТ" \
-H "Content-Type: application/json" \
-d '{"id": 1052, "customer": "Анна", "total": 1500}'
Ответ 200 с телом OK означает, что запрос принят. Такой ответ ждут платёжные сервисы и конструкторы сайтов, например ЮKassa, Т-Банк и Tilda. Скрипт выполняется уже после ответа, поэтому его результат во внешний сервис не возвращается. Посмотреть результат можно в журнале скрипта.
Защита
| Защита | Как работает |
|---|---|
| Секретный ключ | всегда включён; запрос без верного ключа отклоняется |
| Разрешённые IP-адреса | до 20 адресов или подсетей (CIDR), например 203.0.113.10, 198.51.100.0/24; запросы с других адресов отклоняются |
| HMAC-подпись | сервис подписывает тело запроса ключом по алгоритму HMAC-SHA256 и передаёт подпись в заголовке (по умолчанию X-Signature); запрос без верной подписи отклоняется |
Подпись принимается в виде hex, base64 или base64url, допускается префикс sha256=. Ключ подписи (от 8 до 200 символов) берётся из настроек внешнего сервиса и после сохранения скрывается.
Если 20 запросов подряд не прошли проверку адреса или подписи, триггер выключается, а владельцу скрипта приходит письмо. Включить его снова можно на вкладке «Триггеры».
Коды ответа
| Код | error | Что значит |
|---|---|---|
| 200 | — | тело OK: запрос принят, скрипт запустится |
| 401 | webhook_bad_signature | подписи нет или она неверная |
| 403 | webhook_ip_not_allowed | адрес отправителя не входит в разрешённые |
| 403 | webhook_disabled | триггер выключен |
| 403 | scripts_plan_required | скрипты недоступны на тарифе владельца |
| 404 | webhook_not_found | неизвестный адрес или неверный секрет |
| 405 | webhook_method_not_allowed | нужен метод POST |
| 413 | webhook_too_large | тело больше 100 КБ |
| 422 | webhook_invalid_body | тело не в кодировке UTF-8 |
| 429 | webhook_rate_limited | больше 60 запросов в минуту на один адрес |
| 429 | webhook_queue_full | слишком много запросов ждут обработки |
| 429 | scripts_quota_exceeded | закончились минуты скриптов на сегодня |
Ответы с ошибкой приходят в JSON: {"message": "…", "error": "код"}. При ответе 429 заголовок Retry-After подсказывает, через сколько секунд повторить запрос.
Если запросы приходят часто
Запросы, пришедшие, пока скрипт работает, встают в очередь и обрабатываются по порядку. Если очередь переполнена, Coverse отвечает 429 с ошибкой webhook_queue_full, и сервис может повторить запрос позже. Каждая обработка расходует минуты скриптов, поэтому для потока в сотни запросов в минуту лучше подойдёт API с записью из вашей системы напрямую.
Если, наоборот, ваш сервис должен сам писать в таблицу или получать уведомления о её изменениях, используйте API Coverse Таблиц: см. Первая интеграция.
Частые вопросы
Как принять данные из внешнего сервиса в таблицу?
Создайте триггер «По вебхуку»: появится секретный адрес. Сервис отправляет на него POST-запрос, Coverse отвечает 200 OK, а скрипт получает тело, параметры и заголовки запроса.
Как защитить адрес вебхука?
Адрес содержит секрет. Дополнительно можно ограничить IP-адреса отправителей, включить проверку HMAC-подписи или передавать секрет в заголовке X-Coverse-Token.
Что отвечает вебхук скрипта?
При успешном приёме — 200 с телом OK до запуска скрипта. Ошибки приходят в JSON с кодом 401, 403, 404, 413 или 429.
Что дальше
- Готовые сценарии: приём заказов и заявок.
- Заявки с сайта на Tilda в таблицу
- Оплаты ЮKassa и Т-Банка в таблицу
- Интеграция с 1С: 1С отправляет документы в таблицу.
- Остатки и заказы МоегоСклада: вебхук новых заказов.
- Бот Telegram записывает в таблицу
- Права и безопасность