Webhooks

SMS

VK OK

ВКонтакте (Одноклассники)

ЗВОНКИ И ГОЛОСОВЫЕ ОПОВЕЩЕНИЯ

КАСКАД

Каскадная рассылка

ТОКЕН

Авторизация по токену

E-MAIL

Webhooks

Вы можете управлять вебхуками в кабинете сервиса, в разделе Автоматизация -> Webhooks, либо используя API описанный в этом разделе.

Механизм вебхуков позволяет получать POST запросы на указанный URL, о событиях, связанных с отправленными сообщениями. Вебхуки приходят раз в 10 минут группами не более 500 событий в одном запросе. Вы можете настроить типы сообщений, а также события, о которых хотите получать уведомления. Доступные типы сообщений: API/SMTP, рассылки, триггеры, одиночные по шаблону. Доступные события: Доставлено, Не доставлено, Пропущено, Открытие, Переход, Жалоба, Отписка.

Пример данных из полученного POST запроса:

{
"meta": {
  "type": "campaign",
  "id": 1,
  "name": "Рассылка постоянным клиентам"
},
"events": [
    {
      "id": 1164,
      "name": "delivered",
      "email": "example@gmail.com",
      "timestamp": 1684400000
    }
]

Каждый запрос содержит параметры meta и events. Параметр meta это хеш который содержит информацию о том к чему относятся события из данного запроса.

Поля параметра meta

Поле	Пример	Значения	Обязательно	Описание
type	campaign	campaign - обычная рассылка, campaign_transactional - одиночные по шаблону, campaign_workflow - триггерная рассылка, api - API или SMTP трафик	Да	Объект, с которым связаны пришедшие в вебхук события
id	1	число	Да для всех типов кроме api	ID рассылки
name	Рассылка постоянным клиентам	строка	Да для всех типов кроме api	Название рассылки

Параметр events это массив событий связанных с meta

Поля элемента массива events

Поле	Пример	Значения	Обязательно	Описание
id	1164		Да	id сообщения
name	delivered	delivered - доставлено, skipped - пропущено (при отправке на отписанных), soft_bounced - не доставлено, hard_bounced - не доставлено, opened - открытие, unsubscribed - отписка, complained - жалоба, clicked - переход по ссылке	Да	Название события
email	example@gmail.com		Да	Email адрес
timestamp	1684400000		Да	Время события
url	https://ya.ru		Да для clicked	Ссылка
user_agent	Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/105.0.0.0 Safari/537.36		Да для clicked	Информация о браузере
ip	1.1.1.1		Да для clicked	Ip адрес
browser	Chrome		Да для clicked	Браузер
os	Windows		Да для clicked	Операционная система
device_type	Desktop		Да для clicked	Тип устройства
country	Russian Federation		Да для clicked	Страна
region	46		Да для clicked	Код региона
city	Saransk		Да для clicked	Город
delivery_status	5.1.1		Да для недоставленных	Код ответа
delivery_response	Invalid mailbox		Да для недоставленных	Текст ответа

Пример для рассылки, в которой одно доставленное сообщение, открытие, переход и отписка.

{
  "meta": {
      "id": 1,
      "name": "Рассылка постоянным клиентам",
      "type": "campaign"
    },
  "events": [
    {
      "id": 1170,
      "name": "delivered",
      "email": "example@gmail.com",
      "timestamp": 1684400000
    },
    {
      "id": 1171,
      "name": "opened",
      "email": "example@gmail.com",
      "timestamp": 1684401111
    },
    {
      "id": 1172,
      "name": "clicked",
      "email": "example@gmail.com",
      "timestamp": 1684402222,
      "url": "https://ya.ru",
      "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/105.0.0.0 Safari/537.36",
      "ip": "1.1.1.1",
      "browser": "Chrome",
      "os": "Windows",
      "device_type": "Desktop",
      "country": "Russian Federation",
      "region": "46",
      "city": "Saransk"
    },
    {
      "id": 1173,
      "name": "unsubscribed",
      "email": "example@gmail.com",
      "timestamp": 1684403333
    }
  ]
}

Создание вебхука

Пример JSON для запроса

{
    "title": "Api delivered webhooks",
    "url": "https://mysite.org/webhook",
    "kinds": ["api"],
    "events": ["delivered"]
}

Пример запроса

curl -X POST https://app.smsgold.ru/v1/email/messages_webhooks \
     -H 'Content-Type: application/json'             \
     -H 'Authorization: Bearer $API_TOKEN'           \
     -d '...JSON...'

Пример ответа в случае успеха

{
    "id": 1,
    "url": "https://mysite.org/webhook",
    "events": [
        "delivered"
    ],
    "kinds": [
        "api"
    ],
    "status": "active",
    "title": "Api delivered webhooks"
}

POST /email/messages_webhooks

Параметры запроса

Параметр	Описание	Обязательный
title	Название	Да
url	Url для отправки webhooks	Да
kinds	Типы сообщений	Да
events	Список событий	Да

Ответ сервера

Ответ сервера содержит JSON со следующими атрибутами:

Атрибут	Описание
id	Идентификатор
title	Название
url	Url для отправки webhooks
kinds	Типы сообщений
events	Список событий
status	Статус

Список вебхуков

Пример запроса

curl -X GET https://app.smsgold.ru/v1/email/messages_webhooks \
     -H 'Content-Type: application/json'            \
     -H 'Authorization: Bearer $API_TOKEN'

Данный метод поддерживает постраничную выдачу результатов.

Пример ответа в случае успеха

{
    "total_count": 1,
    "total_pages": 1,
    "page_number": 1,
    "page_size": 25,
    "collection": [
        {
            "id": 1,
            "url": "https://mysite.org/webhook",
            "events": [
                "delivered"
            ],
            "kinds": [
                "api"
            ],
            "status": "active",
            "title": "Api delivered webhooks"
        }
    ]
}

GET /email/messages_webhooks

Ответ сервера

Ответ сервера содержит коллекцию вебхуков. Каждый элемент содержит следующие атрибуты:

Атрибут	Описание
id	Идентификатор
title	Название
url	Url для отправки webhooks
kinds	Типы сообщений
events	Список событий
status	Статус

Информация о вебхуке

Пример запроса

curl -X GET https://app.smsgold.ru/v1/email/messages_webhooks/1 \
     -H 'Content-Type: application/json'              \
     -H 'Authorization: Bearer $API_TOKEN'

Пример ответа в случае успеха

{
    "id": 1,
    "title": "Api delivered webhooks",
    "url": "https://mysite.org/webhook",
    "events": [
        "delivered"
    ],
    "kinds": [
        "api"
    ],
    "status": "active"
}

GET /email/messages_webhooks/:id

Ответ сервера

Ответ сервера содержит JSON со следующими атрибутами:

Атрибут	Описание
id	Идентификатор
title	Название
url	Url для отправки webhooks
kinds	Типы сообщений
events	Список событий
status	Статус

Изменение вебхука

Пример JSON для запроса

{
    "events": ["opened"],
    "kinds": ["campaign"],
    "status": "inactive"
}

Пример запроса

curl -X PATCH https://app.smsgold.ru/v1/email/messages_webhooks/1 \
     -H 'Content-Type: application/json'                \
     -H 'Authorization: Bearer $API_TOKEN'              \
     -d '...JSON...'

Пример ответа в случае успеха

{
    "id": 1,
    "title": "Api delivered webhooks",
    "url": "https://mysite.org/webhook",
    "events": [
        "opened"
    ],
    "kinds": [
        "campaign"
    ],
    "status": "inactive"
}

PATCH /email/messages_webhooks/:id

Параметры запроса

Атрибут	Описание
title	Название
url	Url для отправки webhooks
kinds	Типы сообщений
events	Список событий
status	Статус

Ответ сервера

Ответ сервера содержит JSON со следующими атрибутами:

Атрибут	Описание
id	Идентификатор
title	Название
url	Url для отправки webhooks
kinds	Типы сообщений
events	Список событий
status	Статус

Удаление вебхука

Пример запроса

curl -X DELETE https://app.smsgold.ru/v1/email/messages_webhooks/1 \
     -H 'Content-Type: application/json'                 \
     -H 'Authorization: Bearer $API_TOKEN'

Пример ответа в случае успеха

{
    "id": 1,
    "title": "Api delivered webhooks",
    "url": "https://mysite.org/webhook",
    "events": [
        "opened"
    ],
    "kinds": [
        "campaign"
    ],
    "status": "inactive"
}

DELETE /email/messages_webhooks/:id

Ответ сервера

Ответ сервера содержит JSON со следующими атрибутами:

Атрибут	Описание
id	Идентификатор
title	Название
url	Url для отправки webhooks
kinds	Типы сообщений
events	Список событий
status	Статус

Запрос доступных типов сообщений

Пример запроса

curl -X GET https://app.smsgold.ru/v1/email/messages_webhooks/kinds \
     -H 'Content-Type: application/json'              \
     -H 'Authorization: Bearer $API_TOKEN'

Пример ответа в случае успеха

{
    "kinds": [
        "campaign",
        "campaign_transactional",
        "campaign_workflow",
        "api"
    ]
}

GET /email/messages_webhooks/kinds

Запрос доступных событий

Пример запроса

curl -X GET https://app.smsgold.ru/v1/email/messages_webhooks/events \
     -H 'Content-Type: application/json'              \
     -H 'Authorization: Bearer $API_TOKEN'

Пример ответа в случае успеха

{
    "events": [
        "delivered",
        "hard_bounced",
        "skipped",
        "opened",
        "clicked",
        "unsubscribed",
        "complained",
        "soft_bounced"
    ]
}

GET /email/messages_webhooks/events

Рекламные/
Сервисные рассылки

Авторизация/
Аутентификация

В реестре отечественного ПО

Webhooks

SMS

VK OK

ЗВОНКИ И ГОЛОСОВЫЕ ОПОВЕЩЕНИЯ

TELEGRAM

КАСКАД

ТОКЕН

E-MAIL

Webhooks

Поля параметра meta

Поля элемента массива events

Создание вебхука

Параметры запроса

Ответ сервера

Список вебхуков

Ответ сервера

Информация о вебхуке

Ответ сервера

Изменение вебхука

Параметры запроса

Ответ сервера

Удаление вебхука

Ответ сервера

Запрос доступных типов сообщений

Запрос доступных событий