Demo
Demo
База знаний PMTA›Блок <acct-file>›Директива§ 3.3.11.17

http-webhook-url

<acct-file>Хаб задаёт сам

Адрес, на который узел отправляет записи учёта
в конфигурации это строкаhttp-webhook-urlвнутри блока <acct-file>
Учёт, который узел шлёт сам

Обычно записи учёта лежат файлом, и забирать их надо с узла. Эта строка переворачивает направление: узел сам отправляет пачки записей на указанный адрес запросом POST.

Файл при этом остаётся, и это главное, что надо понять. Путь в теге <acct-file> никуда не девается — он становится промежуточным хранилищем. Записи копятся в файле, файл уходит на адрес и удаляется только после успешной отправки.

Успех — это ответ 2xx и ничего больше. Любой другой ответ вызывает повтор через небольшую задержку. Значит, недоступный приёмник даёт накопление, а не потерю — до тех пор, пока не кончится место на диске.

Расширение в пути решает формат. .json — записи в NDJSON и заголовок application/x-ndjson; любое другое расширение — CSV и text/csv. Переопределить тип можно только файлом заголовков (http-webhook-extra-headers).

Главная ловушка — приёмник, который отвечает не 2xx постоянно. Неверный токен, слишком большая пачка, ошибка в приложении — MTA будет повторять бесконечно, а промежуточные файлы копиться. Отказ приёмника выглядит не как ошибка учёта, а как растущий диск.
Что делает Хаб. Пишет — это и есть наша телеметрия. Адрес собирается как <адрес Хаба>/api/telemetry/pmta/<номер узла>, и блок целиком выглядит так: записи d, b, rb, t, feedback-loop, поля по умолчанию с добавками — время первой попытки, время в очереди, число попыток, заголовок Feedback-ID, — пачка раз в минуту, потолок 1 МБ.

Если у Хаба локальный адрес, блок не пишется вовсе — узлу некуда достучаться. Тогда телеметрия идёт опросом через управляющий интерфейс, и это видно в журнале применения конфигурации.

Приёмник отвечает быстро и намеренно. TelemetryController проверяет токен, кладёт тело в кэш и ставит задачу — разбор идёт в фоне. Иначе наша аналитика тормозила бы чужой почтовый сервер: MTA ждёт 2xx.

Рекомендуемые значения

Адрес нужен полный, и лучше по имени, а не по адресу:

Что Замечание
схема https — иначе токен пойдёт открытым текстом
порт не указан — 443 для https, 80 для http
имя узла полное; неполное MTA дополнит для DNS, но в заголовке Host оставит как есть
адрес IPv6 в квадратных скобках

Расширение файла в теге блока — часть настройки: .json даёт NDJSON, всё остальное — CSV.

Разбор адреса, правило промежуточных файлов, условие успеха 2xx и зависимость формата от расширения — из руководства (§ 3.3.11.17, § 12.1.1). Разбор нашего блока телеметрии — по коду Хаба.
Пример в конфигурации
# так это выглядит у нас: расширение .json обязательно
<acct-file /var/log/pmta/mtahub-webhook.json>
    records d, b, rb, t, feedback-loop
    record-fields d  *
    http-webhook-url https://hub.example.com/api/telemetry/pmta/7    http-webhook-extra-headers /etc/pmta/mtahub-headers.txt
    http-webhook-max-interval 1m
    max-size 1M
</acct-file>
Токена в адресе нет намеренно: он лежит в файле заголовков, иначе попал бы в журналы веб-сервера принимающей стороны.
жёлтым — — имена директив, голубым — блоки. Так же они подсвечены и в тексте карточки.
▲

Типичные ошибки и проблемы

что делают не так и чем это кончается3 ошибки▶

Считают вебхук потоком без файлов на диске

§ 12.1.1

Чем чреватоЗаписи всё равно копятся файлом по указанному пути. Место на диске нужно так же, как при обычном учёте, а при недоступном приёмнике — больше.
Как заметитьДиск заполняется при «отключённом файловом учёте».
Как правильноСледить за каталогом промежуточных файлов и за ответами приёмника, а не только за свободным местом.

Меняют расширение пути, не подумав о формате

§ 12.1.1

Чем чреватоФормат записей и заголовок типа содержимого берутся из расширения. .log вместо .json — и приёмник получит CSV с text/csv вместо NDJSON, а разбирать пачку будет нечем.
Как заметитьПриёмник отвечает ошибкой разбора при исправной отправке.
Как правильноОставлять .json для NDJSON; тип содержимого при необходимости переопределять файлом заголовков.

Кладут токен в адрес вместо файла заголовков

наш опыт

Чем чреватоАдрес попадает в журналы веб-сервера принимающей стороны, а с ним и токен. Отозвать его потом дешевле, чем вычистить журналы.
Как заметитьВ адресе вебхука видна длинная случайная строка.
Как правильноПереносить токен в файл http-webhook-extra-headers заголовком Authorization.
Совместимость
PowerMTA 6.0
описана в руководстве этой версии · платформа: любая
С какой версии директива доступна, вендор указывает не для всех — здесь пометки нет. Имя встречается и в издании руководства 5.0.
Справочные данные
Синтаксис
http-webhook-url <url>
Значения
http[s]://ХОСТ[:ПОРТ][/ПУТЬ]
Применение
reload, перезапуск не нужен
Очередь
уже поставленное в очередь не затронет
Где писать
<acct-file>
Сколько раз
один раз в блоке
Всё здесь — из руководства, с разделом.
Наследование
Наследования нет: строка живёт внутри своего <acct-file> и действует на его поток записей. Блоков учёта может быть несколько, и у каждого свой адрес — файловый и вебхук могут работать одновременно, что делает переход безопасным.
⇄

Связанные директивы

5 связей

Зависит от

CSV или JSON — выбирает расширение файла, а не директиваРасширение в пути решает и формат записей, и заголовок типа содержимого в запросе. § 12.1.1

Работают в паре

http-webhook-max-interval<acct-file>Одно называет, куда слать, другое — как часто собирать пачку. § 3.3.11.21

На что влияет

max-size<acct-file>Второе ограничение пачки: она уходит по времени или по размеру, что наступит раньше. § 3.3.11.4

Где применяется

Файл, программа или эндпоинт — и файл под каждым из трёхТретий способ отдать записи учёта; правила промежуточных файлов, повторов и заголовка описаны там. § 12.1.1Договор о телеметрииПревращает поток учёта из файла на диске в отправку по сети; сам файл при этом никуда не девается. § 3.3.11.17

Сюда ссылаются

http-webhook-extra-headers<acct-file>Заголовки добавляются к тому самому запросу, которым уходит пачка. § 3.3.11.18http-webhook-certificate<acct-file>Сертификат предъявляется при обращении к тому адресу. § 3.3.11.19http-webhook-ca-file<acct-file>По этим центрам проверяется сертификат того адреса. § 3.3.11.20http-webhook-transfer-encoding<acct-file>Сжимает содержимое того самого запроса, которым уходит пачка. § 3.3.11.22http-webhook-log-verbose<acct-file>Подробнее пишет в журнал про отправку пачек на тот адрес. § 3.3.11.23http-webhook-connect-timeout<acct-file>Ограничивает ожидание при установлении соединения с тем адресом. § 3.3.11.24

Как проверить на узле
Первый признак исправного вебхука — пустой каталог промежуточных файлов: они удаляются после успешной отправки.
ls -la /var/log/pmta/mtahub-webhook*
Растущее число файлов означает, что приёмник не отвечает 2xx. Причину покажет журнал MTA; подробностей добавит http-webhook-log-verbose. Со стороны приёмника пачку можно подделать: curl -X POST -H ‘Authorization: Bearer ТОКЕН’ -H ‘Content-Type: application/x-ndjson’ –data-binary @batch.json АДРЕС.
◇

Что ещё почитать

3 статьи

◇Что узел рассказывает о себе и по каким каналамСемь поверхностей наблюдения: веб-монитор, консоль в четырёх форматах, журнал, учёт, поиск по учёту, метрики и выгрузка во внешнюю аналитику.◇Два обработчика входящих отчётов и что с ними делатьОтказы письмом и жалобы разбираются двумя одинаково устроенными блоками; у каждого свой список адресов и своя пара решений о судьбе письма.◇Пять способов очереди отдать письмоОчередь не обязана ходить по SMTP: она умеет писать в файл, запускать программу, стучаться по HTTP или выбрасывать.

В Хабе
Значение
Хаб подбирает сам — темп, стадия прогрева, метрики
Цена ошибки
обратимо: вредит, пока стоит
Сценарии
Собрать телеметрию
Соседние настройки блока <acct-file>:http-webhook-max-intervalhttp-webhook-extra-headershttp-webhook-max-connectionshttp-webhook-connect-timeouthttp-webhook-ca-fileВсе 26 директив блока →