Глоссарий
Webhook (вызов на событие)
Webhook это вызов одного сервера другим в тот миг, когда что-то случилось, вместо ожидания вопроса.
Вызов вместо вопроса
Опрос это программа, стучащаяся в дверь каждые несколько секунд. Он стоит трафика обеим сторонам, а нужная новость всё равно приходит с опозданием.
Вызов на событие переворачивает это. Ваш сервер молчит, пока ничего не происходит, а потом стучатся уже к нему.
Вы даёте адрес
Любой свой адрес, отвечающий из открытой сети. До страницы, живущей только внутри вашей сети, из нашей не дотянуться.
Вы отмечаете события
Шлётся только отмеченное, поэтому приёмник, сделанный под одну задачу, не завален всем остальным.
Вы получаете секрет
Этим секретом подписан каждый вызов, и он же позволяет отличить наш вызов от чужого.
Что несёт один вызов
Вызов это обычная посылка с небольшим телом. Заголовки называют событие и несут доказательство того, что тело наше.
- Способ
- POST, Content-Type application/json
- X-Armanos-Event
- profile.start
- X-Armanos-Timestamp
- Секунды Unix, они же часть подписи
- X-Armanos-Signature
- sha256=... от времени и тела вместе
- Тело
- { id, event, createdAt, data }
- Доставка
- Хотя бы один раз. Храните id и отбрасывайте повтор
Переадресация не исполняется. Ответ «перейди на 127.0.0.1» иначе отменял бы всю проверку адреса, поэтому отвечать обязан тот адрес, который вы дали.
События для подписки
Список один на весь кабинет: те же имена предлагаются вам, ими же проверяется подписка и по ним же решается, что отправлять.
Профили
profile.create, profile.update, profile.delete, profile.start, profile.stop
Прокси
proxy.create, proxy.update, proxy.delete
Ключи
apikey.create, apikey.revoke
Команда
team.invite, team.remove
Деньги
plan.change
Второй список означал бы невыполнимое обещание
Как узнать наш вызов
Подпись это свёртка времени и тела вместе, снятая секретом, который есть только у вас и у нас. Повторите тот же рецепт у себя и сравните.
Сравнивайте за постоянное время. Сверка, обрывающаяся на первом несовпавшем знаке, тихо подсказывает подбирающему, докуда он дошёл.
Время лежит внутри подписи
Когда ваш сервер не отвечает
Вызов повторяется трижды с растущей паузой, и каждая попытка ждёт ответа десять секунд. Повторять стоит только то, что не вышло на вашей стороне провода.
Когда попытки кончились, итог пишется в саму подписку: код последней попытки, причину словами и время. После пятнадцати неудач подряд подписка выключается сама и называет причину.
Ошибка сервера или просьба подождать
Повторяем: тот же вызов вполне может пройти секундой позже.
Не найдено или отказано
Не повторяем. Через секунду адрес останется таким же неверным, и долбиться в него бессмысленно.
Тишина
Считается неудачей по истечении ожидания, и записывать в ответ нечего.
Чего это не делает
- Доставка идёт хотя бы один раз, а не ровно один, и отбрасывать повтор по номеру вызова ваша часть уговора. Вызов, исчерпавший все попытки, для поздней отправки не сохраняется.
- Вызов это не сам предмет. Поля, чьи имена похожи на пропуск, снимаются перед отправкой, поэтому код приглашения и ссылка сброса пароля не уезжают на чужой сервер.
- События рождаются на нашем сервере. Работа, сделанная на вашем компьютере и до нас не дошедшая, не поднимает никакого вызова.
- Подписку заводит человек, вошедший паролем, а не ключ, и принадлежит она аккаунту, а не одной папке. Отбор до папки делается на вашей стороне.
Проверить
Каждое утверждение выше указывает на файл, который это делает, и на стенд, который это стережёт.
- Тело подписывается, и тот же код сверяет подпись так же, как это сделаете вы
- apps/server/src/webhooks/webhook-dispatch.service.ts
- Адрес, смотрящий внутрь частной сети, проверяется перед каждой отправкой
- apps/server/src/webhooks/webhook-guard.ts · apps/server/test/webhooks.js
- Список событий один, и поля, дающие вход, из него вычищаются
- apps/server/src/webhooks/webhook-events.ts
- Неудачная доставка видна в кабинете, а не пропадает молча
- apps/web/test/webhooks-web.js
Вопросы
- Что должен отвечать мой приёмник?
- Любой код из двухсотых, и как можно быстрее. Настоящую работу делайте после ответа: медленный ответ выглядит как неудача и заработает повтор.
- Можно ли проверить, не дожидаясь настоящего события?
- Да. Пробный вызов уходит на ваш адрес по требованию и помечен как проба, поэтому ваша система не заведёт себе несуществующий профиль.
- Почему подписка выключилась сама?
- Пятнадцать неудач подряд. Причина написана в самой подписке, а включение вручную начинает счёт заново.
- Сломает ли мою работу мёртвый приёмник?
- Нет. Отправка идёт фоном, когда действие уже сделано, поэтому запущенный профиль останется запущенным, пока ваш сервер лежит.
- Сколько подписок можно держать?
- Десять. Каждая это наш сервер, стучащийся наружу от вашего имени, и по той же причине стоит предел у ключей.
Направьте вызов на свой сервер
Дайте адрес, отметьте события и пошлите пробный вызов до того, как случится настоящее.