Как прослушивать вебхуки с помощью Python

Веб-перехватчики запускают большую часть «волшебства», которое происходит между приложениями. Их иногда называют обратными API, обратными вызовами и даже уведомлениями. Многие сервисы, такие как SendGrid, Stripe, Slack и GitHub, используют события для отправки веб-перехватчиков как часть своего API. Это позволяет вашему приложению прослушивать события и выполнять действия, когда они происходят.

В предыдущей статье мы рассмотрели, как использовать веб-хуки с помощью Node.js и Express. В этой статье мы рассмотрим, как вы можете прослушивать веб-хуки с помощью Python (v3+) с Колба или же Джанго рамки.

Вы можете перейти непосредственно к коду для любого фреймворка по одной из ссылок ниже:

• Получите вебхук с помощью Flask
• Получите вебхук с Django

В этом руководстве предполагается, что на вашем компьютере установлен Python v3. Вы можете найти подробную информацию об установке python на странице официальная страница загрузок. В зависимости от вашей настройки, python команда, которую вы хотите использовать, может быть python3.

Вы можете подтвердить установленную версию, запустив в терминале следующее:

python --version

или, если это отображает версию ниже 3:

python3 --version

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

Что такое вебхук

Веб-хуки не просто так называются обратными API. Вместо того, чтобы ваше приложение отправляло запрос к API, API отправляет запрос вашему приложению. Хотя концепция может звучать по-разному, способ, которым мы используем веб-перехватчики, такой же, как API использует запрос.

В большинстве веб-фреймворков есть понятие маршрута. Маршрут позволяет приложению отвечать определенным содержимым или данными, когда пользователь посещает определенный URL-адрес. Та же идея применима и к API. Когда вы отправляете запрос на GitHub для получения подробной информации о конкретной организации, например https://api.github.com/orgs/Bearerмаршрут такой /orgs/:org куда :org это название организации.

Та же концепция применяется при получении веб-хуков. Мы устанавливаем маршрут, сообщаем сервису, куда отправлять данные, а наше приложение сидит и ждет, пока не придет запрос на этот маршрут.

В реализациях веб-перехватчиков есть несколько общих черт.

1. Они обычно POST Запросы.
2. Они получают данные JSON.
3. Им нужно быстро реагировать.

Некоторые API требуют, чтобы ваше приложение ответило в течение определенного периода времени, иначе событие будет отправлено повторно. Например, Слабый API ожидает ответа в течение трех секунд.

Получите вебхук с помощью Flask

Каркас фляги это легкая веб-инфраструктура Python, которая описывает себя как «микро». Это позволяет вам использовать только то, что вам нужно, а затем добавлять дополнительную структуру по мере роста вашего проекта.

Для наших целей это отлично, поскольку нас интересует только маршрутизация. Убедитесь, что Python установлен, затем выполните следующую команду в своем терминале, чтобы установить flask:

python -m pip install Flask

Полную информацию об установке и настройке можно найти на странице Фляжная документация.

Далее создайте .py файл, например main.py и добавьте следующее:

from flask import Flask, request, Response

app = Flask( __name__ )

@app.route('/webhook', methods=['POST'])
def respond():
    print(request.json);
    return Response(status=200)

Этот код импортирует класс Flask вместе с объектами запроса и ответа. Затем создает экземпляр с именем __name__ перед назначением его на app переменная. Эта схема именования является соглашением в документации Flask.

Далее мы используем @app.route декоратор для прослушивания POST запросы, направленные против /webhook дорожка. Этот декоратор вызывает функцию, которая сразу следует за ним, когда делается запрос к маршруту. В данном случае это respond функция.

Для целей этого примера мы print из запроса как json, затем вернуть Response с кодом состояния 200. Этот ответ сообщает отправителю, что мы получили хук. Вы должны иметь возможность запускать сервер, используя предпочтительный метод Flask:

export FLASK_APP=main.py
python -m flask run

Вот оно! Теперь у нас есть приложение, которое прослушивает веб-перехватчик с помощью python и flask. После развертывания POST запросы к конечной точке вызовут respond функция. Например: https://exampledomain.com/webhook. Это также URL-адрес, который вы предоставите службе, которая отправляет веб-перехватчик.

Получите вебхук с Django

Настройка приложения в Django более автоматизирована, чем в Flask, но также имеет более сложную файловую структуру. Как более традиционная структура Model-View-Controller (MVC), Django формирует для вас основные части проекта. Полное руководство по установке доступно на официальная страница документации Djangoно его также можно установить с помощью pip используя следующую команду:

python -m pip install Django

Если вы настраиваете проект с нуля, используйте django-admin утилита для создания нового проекта. Если у вас уже есть проект Django, в который вы хотите добавить веб-перехватчики, перейдите к следующему шагу.

django-admin startproject example-project

Это создает основу для нового проекта Django. Перейдите к вновь созданной папке, и вы должны увидеть структуру, подобную следующей:

example-project/
    manage.py
    example-project/
    __init__.py
    settings.py
    urls.py
    asgi.py
    wsgi.py

Мы можем подтвердить, что все работает, запустив python manage.py runserver.

Соглашение Django заключается в настройке «приложений» внутри этого внешнего «проекта». Вы можете избежать этого и настроить проект с одним приложением, запустив django-admin startproject example-project . с завершающей точкой (.) вместо этого. В этом уроке мы будем отражать предпочтительный способ, как показано ранее.

Для этого мы настроим «приложение» под названием вебхуки.

python manage.py startapp webhooks

Это создает новый каталог с именем вебхуки. Большой! Теперь мы можем написать код. Мы сосредоточимся на трех файлах: webhooks/views.py, webhooks/urls.py (еще не создано) и example-site/urls.py.

Откройте файл webhooks/views.py. Здесь мы напишем логику обработки маршрута.

from django.http import HttpResponse
from django.views.decorators.http import require_POST

@require_POST
def example(request):
  return HttpResponse('Hello, world. This is the webhook response.')

Этот код делает следующее:

• Он импортирует HttpResponse объект, который будет использоваться для отправки ответа.
• Он импортирует специальный декоратор для ограничения метода запроса. В Django маршруты принимают все методы HTTP по умолчанию и позволяют представлениям управлять тем, на какие методы они отвечают.
• Вызывает декоратор, чтобы ограничить следующую функцию только POST метод.
• Определяет функцию с именем example который принимает запрос в качестве аргумента и возвращает ответ.

Этот example имя функции будет связано с нашим urls.py файл в ближайшее время. Ему не нужно выравниваться по определенному пути.

Далее создайте webhooks/urls.py если он еще не существует. Здесь мы организуем маршруты в этом подприложении нашего проекта.

from django.urls import path

from . import views

urlpatterns = [
    path('example/', views.example)
]

Здесь мы импортируем path из django.urls. Он определяет отдельные маршруты и связывает их с представлениями. Затем мы импортируем все представления. Окончательно, urlpatterns передается список путей. Этот список распознается Django как маршруты, связанные с приложением.

В этом случае мы определяем путь, который нацелен example/ и связан с представлением views.exampleтак называлась наша функция в views.py.

После этого наше приложение работает, но нам нужно сообщить об этом внешнему проекту. Открытым example-project/urls.py. Он должен выглядеть аналогично предыдущему файлу, но с существующим admin маршрут. Добавьте новый путь следующим образом:

urlpatterns = [
    path('admin/', admin.site.urls),
    path('webhooks/', include('webhooks.urls'))
]

Если ваш сервер остановился, запустите его снова с помощью python manage.py runserver. Теперь попробуйте сделать POST-запрос на (замените хост и порт на свои, если они отличаются).

При этом мы создали проект Django, который прослушивает веб-перехватчик на /webhooks/example. После развертывания добавьте этот путь к полному URL-адресу и предоставьте полный URL-адрес службе, которая отправляет веб-перехватчик.

Локальное тестирование вебхуков

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

Один из вариантов — использовать юбка. Эта служба позволяет вам предоставлять внешний доступ к определенному порту на вашем локальном компьютере. Это отлично подходит для наших нужд. Для начала зарегистрируйтесь и следуйте инструкциям по установке и началу работы.

После этого, если вы работаете в MacOS, вы сможете запустить ./ngrok http 3000 в вашем терминале, где 3000 заменен на порт вашего работающего приложения Python. Например, сайт Django по умолчанию часто работает на порту 8000.

После запуска ngrok предоставит вам URL-адрес, который вы можете использовать для проверки своего веб-перехватчика. В Bearer мы предоставляем кнопку «тест» в настройках уведомлений.

После настройки вы начнете получать веб-перехватчики по этому URL-адресу. Не забудьте изменить его на окончательный развернутый URL-адрес веб-перехватчика после завершения разработки и тестирования.

После настройки веб-перехватчика вы сами решаете, как обрабатывать получаемую информацию. Вы можете использовать эту информацию, чтобы реагировать на события в режиме реального времени, использовать обратные части вашего приложения или даже использовать ее как способ записи данных в базу данных. Ваш веб-перехватчик может иметь бесчисленное множество возможностей в зависимости от того, какую информацию отправляет поставщик API.

Хотя в этой статье мы построили базовую реализацию, стоит упомянуть, что многие службы предлагают способы проверки того, что запрос исходит из фактического источника. Это можно сделать, ограничив URL-адреса, которые обращаются к вашему приложению, или сопоставив секретный ключ. GitHub, например, позволяет вам установить секрет, который будет отправляться с каждым веб-перехватчиком.

Изучите документацию по службам, которые вы используете, чтобы узнать, как лучше всего работать в их настройке. Если вам нравится идея использования веб-перехватчиков для реагирования на изменения мониторинга с вашими сторонними поставщиками API, посмотрите, что мы строим на Bearer.sh.