Связаться с намиПодключиться

Интеграция Yandex Cloud Postbox с внешними системами с помощью вебхуков

Статья создана
Обновлена 31 октября 2025 г.

Важно

Часть ресурсов, необходимых для прохождения практического руководства, доступны только в регионе Россия.

В этом руководстве вы настроите передачу событий Yandex Cloud Postbox в Yandex Data Streams и вызов вебхуков во внешних системах. Для обработки и хранения данных будут использоваться сервисы Yandex Cloud Functions и Yandex Managed Service for YDB.

Реализовать предлагаемое решение можно с помощью консоли управления Yandex Cloud, даже не имея навыков разработки.

Чтобы настроить передачу событий и их обработку:

  1. Подготовьте облако к работе.
  2. Создайте сервисные аккаунты.
  3. Создайте статический ключ доступа.
  4. Создайте базу данных Managed Service for YDB.
  5. Создайте поток данных Data Streams.
  6. Подготовьте ресурсы Yandex Cloud Postbox.
  7. Подготовьте ресурсы Cloud Functions.
  8. Протестируйте работу решения.

Если созданные ресурсы вам больше не нужны, удалите их.

Подготовьте облако к работе

Зарегистрируйтесь в Yandex Cloud и создайте платежный аккаунт:

  1. Перейдите в консоль управления, затем войдите в Yandex Cloud или зарегистрируйтесь.
  2. На странице Yandex Cloud Billing убедитесь, что у вас подключен платежный аккаунт, и он находится в статусе ACTIVE или TRIAL_ACTIVE. Если платежного аккаунта нет, создайте его и привяжите к нему облако.

Если у вас есть активный платежный аккаунт, вы можете создать или выбрать каталог, в котором будет работать ваша инфраструктура, на странице облака.

Подробнее об облаках и каталогах.

В стоимость поддержки инфраструктуры входят:

Создайте сервисные аккаунты

Создайте два сервисных аккаунта:

  • yds-functions — от его имени будет вызываться функция Cloud Functions и будут записываться события в поток данных Data Streams;
  • postbox-user — от его имени будут отправляться письма через Yandex Cloud Postbox.

  1. Создайте сервисный аккаунт yds-functions:

    1. В консоли управления выберите каталог, в котором вы будете создавать инфраструктуру.
    2. В списке сервисов выберите Identity and Access Management и нажмите кнопку Создать сервисный аккаунт.
    3. В поле Имя укажите имя yds-functions.
    4. Нажмите кнопку Добавить роль и выберите роли yds.editor и functions.functionInvoker.
    5. Нажмите кнопку Создать.

  2. Аналогичным образом создайте сервисный аккаунт postbox-user и назначьте ему роль postbox.sender.

Создайте статический ключ доступа

Создайте статический ключ доступа, который будет использоваться для отправки писем:

  1. В консоли управления выберите каталог, в котором вы создаете инфраструктуру.

  2. В списке сервисов выберите Identity and Access Management и в списке сервисных аккаунтов выберите postbox-user. В открывшемся окне:

    1. На панели сверху нажмите кнопку Создать новый ключ и выберите Создать статический ключ доступа.

    2. Нажмите кнопку Создать.

    3. Сохраните идентификатор и секретный ключ.

      Внимание

      После закрытия диалога значение ключа будет недоступно.

Создайте базу данных Managed Service for YDB

Чтобы создать поток данных, в который будут отправляться события Yandex Cloud Postbox, потребуется база данных Managed Service for YDB. Создайте бессерверную базу данных Managed Service for YDB:

  1. В консоли управления выберите каталог, в котором вы создаете инфраструктуру.
  2. В списке сервисов выберите Managed Service for YDB и нажмите кнопку Создать базу данных.
  3. В поле Имя укажите postbox-events-ydb.
  4. В поле Тип базы данных выберите Serverless.
  5. Другие параметры базы данных оставьте без изменений и нажмите кнопку Создать базу данных.

Дождитесь запуска БД. В процессе создания база данных будет находиться в статусе Provisioning, а когда станет готова к использованию, ее статус изменится на Running.

Создайте поток данных Data Streams

Создайте поток данных, в котором будут регистрироваться события Yandex Cloud Postbox:

  1. В консоли управления выберите каталог, в котором вы создаете инфраструктуру.
  2. В списке сервисов выберите Data Streams и нажмите кнопку Создать поток.
  3. В поле База данных выберите созданную ранее базу данных postbox-events-ydb.
  4. В поле Имя укажите имя потока данных postbox-events-stream.
  5. В поле Режим тарификации выберите По фактическому использованию.
  6. Другие параметры потока данных оставьте без изменений и нажмите кнопку Создать.

Дождитесь запуска потока данных. Когда поток станет готов к использованию, его статус изменится с Creating на Active.

Подготовьте ресурсы Yandex Cloud Postbox

В сервисе Yandex Cloud Postbox настройте конфигурацию для регистрации событий в Data Streams, создайте адрес для отправки писем и пройдите проверку прав на домен.

Создайте конфигурацию Yandex Cloud Postbox

  1. В консоли управления выберите каталог, в котором вы создаете инфраструктуру.

  2. В списке сервисов выберите Cloud Postbox.

  3. На панели слева выберите Конфигурации и нажмите кнопку Создать конфигурацию.

  4. В поле Имя укажите имя конфигурации postbox-events-config.

  5. В блоке Подписки нажмите кнопку Добавить и в появившейся форме:

    1. В поле Название укажите название подписки postbox-events-subscribe.
    2. В поле Поток данных выберите поток данных postbox-events-stream.
    3. Включите опцию Включено, чтобы активировать подписку.

  6. Другие параметры конфигурации оставьте без изменений и нажмите кнопку Создать конфигурацию.

Создайте адрес Yandex Cloud Postbox

  1. На вашем компьютере сгенерируйте ключ privatekey.pem для создания DKIM-подписи. Для этого в терминале выполните команду:

    openssl genrsa -out privatekey.pem 2048

    Примечание

    В операционных системах Linux и macOS утилита openssl предустановлена. В Windows эту утилиту необходимо предварительно установить. Подробнее см. на сайте проекта.

  2. Создайте адрес Yandex Cloud Postbox:

    1. В консоли управления выберите каталог, в котором вы создаете инфраструктуру.
    2. В списке сервисов выберите Cloud Postbox.
    3. На панели слева выберите Адреса и нажмите кнопку Создать адрес.
    4. В поле Домен укажите домен, с которого вы будете отправлять письма. Домен может быть любого уровня и должен принадлежать вам.
    5. В поле Селектор укажите селектор, например postbox. Указанный селектор должен использоваться только в одной ресурсной записи — той, которую необходимо создать при прохождении проверки прав на домен.
    6. В поле Конфигурация выберите созданную ранее конфигурацию postbox-events-config.
    7. В поле Приватный ключ вставьте содержимое файла приватного ключа privatekey.pem, созданного на предыдущем шаге.
    8. Другие параметры адреса оставьте без изменений и нажмите кнопку Создать адрес.
    9. В открывшемся списке адресов нажмите на строку с вновь созданным адресом.
    10. На странице с информацией об адресе в блоке Подтверждение подписи из поля Значение скопируйте и сохраните значение TXT-записи.

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

Чтобы отправлять письма, подтвердите владение доменом. После создания адреса на его странице сформируются настройки DKIM-подписи. Их нужно указать в качестве значений ресурсной записи, которую необходимо добавить в вашу доменную зону. Вы можете добавить запись у вашего регистратора или в сервисе Yandex Cloud DNS, если вы делегировали ваш домен Yandex Cloud.

Пример создания ресурсной записи в Yandex Cloud DNS

  1. В консоли управления выберите каталог, в котором находятся адрес и ваша доменная зона.

    Если у вас еще нет публичной зоны DNS, создайте ее.

  2. Выберите сервис Cloud DNS.

  3. Выберите вашу доменную зону.

  4. Нажмите кнопку Создать запись.

  5. В поле Имя укажите часть имени, сгенерированного при создании адреса, без домена в формате <селектор>._domainkey. Например postbox._domainkey.

    Примечание

    Для других DNS-сервисов может потребоваться скопировать запись целиком. Итоговая запись должна иметь вид <селектор>._domainkey.<домен>., например postbox._domainkey.example.com..

  6. В поле Тип выберите TXT.

  7. В поле Значение скопируйте содержимое поля Значение из блока Подтверждение подписи. Обратите внимание, что значение записи нужно взять в кавычки, например:

    "v=DKIM1;h=sha256;k=rsa;p=M1B...aCA8"

  8. Нажмите кнопку Создать.

  9. Перейдите в сервис Cloud Postbox.

  10. Выберите созданный адрес.

  11. Нажмите кнопку Проверить адрес. Если запись верна, статус проверки на странице адреса изменится на Success.

Ответы DNS-сервера кешируются, поэтому возможны задержки при обновлении ресурсной записи.

Подготовьте ресурсы Cloud Functions

Создайте функцию, которая будет отправлять вебхук, а также триггер, который будет вызывать эту функцию при регистрации событий в потоке данных.

Создайте функцию

  1. В консоли управления выберите каталог, в котором вы создаете инфраструктуру.

  2. В списке сервисов выберите Cloud Functions.

  3. Создайте функцию:

    1. Нажмите кнопку Создать функцию.
    2. В поле Имя укажите имя функции postbox-webhook.
    3. Нажмите кнопку Создать.

  4. Создайте версию функции:

    1. В открывшемся окне Редактор выберите Python 3.12.

    2. Отключите опцию Добавить файлы с примерами кода.

    3. Нажмите кнопку Продолжить.

    4. В поле Способ выберите Редактор кода.

    5. Создайте 2 файла:

      • файл requirements.txt, содержащий список необходимых зависимостей:

        requests

      • файл index.py, содержащий код функции:

        import requests

# Адрес webhook'а который будет вызван
WEBHOOK_URL = "<URL_вебхука>"


def handler(event, context):
    requests.post(WEBHOOK_URL, json=event)

    return {
        "statusCode": 200,
    }

        Где WEBHOOK_URL — адрес вебхука, на который будет отправлен запрос.

    6. В поле Точка входа укажите index.handler.

    7. В блоке Параметры укажите:

      • Таймаут — 10 секунд.
      • Память — 128 МБ.

    8. Другие параметры версии функции оставьте без изменений и нажмите кнопку Сохранить изменения.

  1. В консоли управления выберите каталог, в котором вы создаете инфраструктуру.

  2. В списке сервисов выберите Cloud Functions.

  3. Создайте функцию:

    1. Нажмите кнопку Создать функцию.
    2. В поле Имя укажите имя функции postbox-webhook.
    3. Нажмите кнопку Создать.

  4. Создайте версию функции:

    1. В открывшемся окне Редактор выберите Node.js 22.

    2. Отключите опцию Добавить файлы с примерами кода.

    3. Нажмите кнопку Продолжить.

    4. В поле Способ выберите Редактор кода.

    5. Создайте файл index.js с кодом функции:

      // Адрес webhook'а который будет вызван
const WEBHOOK_URL = '<URL_вебхука>'

module.exports.handler = async function (event, context) {
    await fetch(WEBHOOK_URL, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
        },
        body: JSON.stringify(event),
    });

    return {
        statusCode: 200,
    };
};

      Где WEBHOOK_URL — адрес вебхука, на который будет отправлен запрос.

    6. В поле Точка входа укажите index.handler.

    7. В блоке Параметры укажите:

      • Таймаут — 10 секунд.
      • Память — 128 МБ.

    8. Другие параметры версии функции оставьте без изменений и нажмите кнопку Сохранить изменения.

Создайте триггер

  1. В консоли управления выберите каталог, в котором вы создаете инфраструктуру.
  2. В списке сервисов выберите Cloud Functions.
  3. На панели слева выберите Триггеры и нажмите кнопку Создать триггер.
  4. В поле Имя введите имя триггера postbox-events-trigger.
  5. В поле Тип выберите Data Streams.
  6. В поле Запускаемый ресурс выберите Функция.
  7. В блоке Настройки Data Streams выберите поток данных postbox-events-stream и сервисный аккаунт yds-functions.
  8. В блоке Настройки функции выберите функцию postbox-webhook и сервисный аккаунт yds-functions.
  9. Нажмите кнопку Создать триггер.

Протестируйте работу решения

  1. Удобным вам способом отправьте несколько тестовых писем с использованием адреса Yandex Cloud Postbox и статического ключа доступа, созданных ранее.

  2. Убедитесь, что письма доставлены. Для этого проверьте почту, на которую вы отправляли эти письма.

  3. Убедитесь, что данные об отправке писем поступают в сервисы:

    • Проверьте поток данных:

      1. В консоли управления выберите каталог, в котором вы создаете инфраструктуру.

      2. В списке сервисов выберите Data Streams.

      3. Выберите поток данных postbox-events-stream.

      4. Перейдите на вкладку Просмотр данных.

        На графиках должны отобразиться события отправки писем.

    • Посмотрите логи функции и графики мониторинга триггера.

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

В результате выполнения руководства вы сможете вызывать вебхуки внешней системы в ответ на события, связанные с отправкой писем через Yandex Cloud Postbox.

Как удалить созданные ресурсы

Чтобы перестать платить за созданные ресурсы:

  1. Удалите триггер для вызова функции Cloud Functions.
  2. Удалите функцию Cloud Functions.
  3. Удалите поток данных Data Streams.
  4. Удалите базу данных Managed Service for YDB.
  5. Удалите адрес и конфигурацию Yandex Cloud Postbox.
  6. При необходимости удалите созданные сервисные аккаунты.
  7. При необходимости удалите ресурсную запись и публичную зону DNS.
Предыдущая
Поиск событий Yandex Cloud в Yandex Query
Следующая
Управление доступом