Webhooks

Последнее изменение: 2 недели назад

1. Что такое Webhooks?

Webhooks — это инструмент для получения и хранения данных о конкретных событиях. Они позволяют зарегистрировать URL-адрес (http:// или https://), куда данные события будут отправляться в формате JSON.

2. Как это работает?

Мы отправляем запрос типа 'POST' на ваш URL с JSON-данными webhook для следующих событий:

topic.created
topic.accepted
topic.satisfaction_changed
comment.created
comment.accepted
comment.deleted

3. Пример данных

{    "hook": "topic.created", 
    "created": "2014-04-25T04:17:38.306Z",
    "data": {
        "id": 439181,
        "header": "Test header", 
        "description": "Test description", 
        "type": {
            "id": 2, 
            "name": "Questions"
        }
        ...
    }, 
}

Поле 'data' содержит сериализованные данные топика или комментария с такой же структурой, как в нашем API. Введение в API.

4. Ответ на webhook

Вы должны отправить HTTP-код ответа 200. Если наш сервер получит другой код ответа, webhook-запрос будет повторно отправлен через 5 минут. Наш сервер ожидает корректный ответ в течение 10 секунд. Рекомендуется сохранять полученные данные в локальной очереди и сразу отправлять ответ нашему серверу, а затем обрабатывать данные на своей стороне.

5. Аутентификация webhook-запросов (необязательно)

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

Проверка подписи запроса
UserEcho добавляет дополнительный HTTP-заголовок к webhook POST-запросам — X-UE-Signature (HTTP_X_UE_SIGNATURE), который содержит подпись запроса. Чтобы проверить подлинность webhook-запроса, сгенерируйте подпись с помощью вашего ключа и сравните её с подписью из заголовка.

Как сгенерировать подпись:
Создайте хэш строки 'POST' с помощью HMAC-SHA1, используя ваш ключ, чтобы получить шестнадцатеричную подпись. Затем сравните её с подписью из заголовка.

Вы можете получить ваш ключ в разделе Настройки → Интеграция → Веб-сайт → Webhooks.

Пример на PYTHON:

def get_signature(key, text):    
    import hmac
    import hashlib
    return hmac.new(str(key), msg=bytearray(text, 'utf-8'), digestmod=hashlib.sha256).hexdigest()

Оставляйте вопросы и идеи по улучшению функционала webhooks здесь:
http://feedback.userecho.com/topic/315761-webhook-for-custom-integrations/