Вебхуки для ваших заданий StarterEnterpriseEnterprise +
С помощью dbt вы можете создавать исходящие вебхуки для отправки событий (уведомлений) о ваших dbt jobs в другие системы. Эти системы могут принимать (подписываться на) такие события, чтобы дальше автоматизировать ваши рабочие процессы или запускать настроенные вами сценарии автоматизации.
Вебхук — это функция обратного вызова на основе HTTP, которая позволяет осуществлять коммуникацию, основанную на событиях, между двумя различными веб-приложениями. Это позволяет получать самую актуальную информацию о ваших задачах dbt в реальном времени. Без этого вам пришлось бы многократно делать вызовы API, чтобы проверить, есть ли какие-либо обновления, которые вам нужно учесть (опрос). Из-за этого вебхуки также называют push API или reverse API и часто используют для разработки инфраструктуры.
dbt отправляет JSON‑полезную нагрузку на endpoint URL вашего приложения, когда срабатывает webhook. Вы можете отправить уведомление в Slack, уведомление в Microsoft Teams или открыть инцидент в PagerDuty, когда задание dbt завершается с ошибкой.
Вы можете создавать webhooks для этих событий через веб‑интерфейс dbt, а также с помощью API dbt:
job.run.started— Запуск начат.job.run.completed— Запуск завершен. Это может быть запуск, который завершился с ошибкой или успешно.job.run.errored— Запуск завершился с ошибкой.
dbt повторно отправляет каждое событие до пяти раз. dbt хранит журнал каждой доставки webhook в течение 30 дней. У каждого webhook есть собственный раздел Recent Deliveries, который позволяет с первого взгляда увидеть, была ли доставка успешной или завершилась с ошибкой.
Webhook в dbt имеет тайм-аут 10 секунд. Это означает, что если конечная точка не отвечает в течение 10 секунд, обработчик webhook завершает работу по тайм-ауту. В результате может возникнуть ситуация, когда клиент успешно отвечает после истечения этих 10 секунд и фиксирует статус успеха, тогда как система webhook в dbt интерпретирует такую доставку как неудачную.
Если вас интересует обучение с помощью видео, ознакомьтесь с курсом по вебхукам на требование от dbt Labs.
Вы также можете ознакомиться с бесплатным курсом Основы dbt.
Предварительные требования
- У вас есть учетная запись dbt, работающая на тарифном плане Starter или Enterprise-tier.
- Для доступа
writeк вебхукам:- Тарифные планы Enterprise-tier — Наборы разрешений одинаковы как для API service tokens, так и для интерфейса dbt. Вы или API service token должны иметь набор разрешений Account Admin, Admin или Developer (permission set).
- Аккаунты на тарифе Starter — Для интерфейса dbt вам необходимо иметь лицензию Developer.
- Вы используете модель развертывания multi-tenant или AWS single-tenant в dbt. Дополнительную информацию см. в разделе Tenancy.
- Ваша целевая система поддерживает Authorization headers.
Создание подписки на вебхук
-
Перейдите в Account settings в dbt (кликнув по имени своей учетной записи в левой боковой панели).
-
Перейдите в раздел Webhooks и нажмите Create webhook.
-
Для настройки нового вебхука:
- Webhook name — Введите имя для исходящего вебхука.
- Description — Введите описание вебхука.
- Events — Выберите событие, при наступлении которого будет срабатывать этот вебхук. Можно подписаться на несколько событий.
- Jobs — Укажите задание(я), для которых должен срабатывать вебхук. Либо оставьте это поле пустым, чтобы вебхук срабатывал для всех заданий в вашей учетной записи. По умолчанию dbt настраивает вебхук на уровне учетной записи.
- Endpoint — Укажите URL эндпоинта вашего приложения, на который dbt сможет отправлять события.
-
По завершении нажмите Save.
dbt предоставляет секретный токен, который вы можете использовать для проверки подлинности вебхука. Настоятельно рекомендуется выполнять эту проверку на стороне вашего сервера, чтобы защититься от поддельных (spoofed) запросов.
Обратите внимание, что dbt автоматически деактивирует вебхук после 5 последовательных неудачных попыток отправки событий на ваш эндпоинт. Чтобы повторно активировать вебхук, найдите его в списке вебхуков и нажмите кнопку повторной активации, чтобы снова включить его и продолжить получать события.
Чтобы найти подходящий URL доступа dbt для вашего региона и тарифного плана, см. Regions & IP addresses.
Различия между событиями completed и errored
Событие job.run.errored является подмножеством событий job.run.completed. Если вы подпишетесь на оба, вы получите два уведомления, когда выполнение задания завершится с ошибкой. Однако dbt инициирует эти два события в разное время:
job.run.completed— это событие срабатывает только после того, как метаданные и артефакты задания будут загружены и станут доступны через Admin и Discovery API dbt.job.run.errored— это событие срабатывает немедленно, поэтому метаданные и артефакты задания могут еще не быть загружены. Это означает, что часть информации может быть недоступна для использования.
Если ваша интеграция зависит от данных из Admin API (например, доступ к журналам запуска) или Discovery API (доступ к статусам моделей), используйте событие job.run.completed и фильтруйте по runStatus или runStatusCode.
Если ваша интеграция не зависит от дополнительных данных или если улучшенная производительность доставки более важна для вас, используйте job.run.errored и настройте вашу интеграцию для обработки вызовов API, которые могут не возвращать данные в течение короткого времени вначале.
Проверка вебхука
Вы можете использовать секретный токен, предоставленный dbt Cloud, чтобы проверить, что вебхуки, полученные вашей конечной точкой, действительно были отправлены dbt Cloud. Официальные вебхуки будут включать заголовок Authorization, который содержит SHA256-хэш тела запроса и использует секретный токен в качестве ключа.
Вы можете использовать секретный токен, предоставленный dbt, чтобы проверить, что вебхуки, полученные вашим эндпоинтом, действительно были отправлены dbt. Официальные вебхуки будут содержать заголовок Authorization, в котором находится SHA256‑хэш тела запроса, вычисленный с использованием секретного токена в качестве ключа.
Ниже приведён пример проверки подлинности вебхука на Python:
auth_header = request.headers.get('authorization', None)
app_secret = os.environ['MY_DBT_CLOUD_AUTH_TOKEN'].encode('utf-8')
signature = hmac.new(app_secret, request_body, hashlib.sha256).hexdigest()
return signature == auth_header
Обратите внимание, что система назначения должна поддерживать заголовки авторизации, чтобы вебхук работал корректно. Вы можете протестировать поддержку вашей конечной точки, отправив запрос с помощью curl и заголовка Authorization, как показано ниже:
curl -H 'Authorization: 123' -X POST https://<your-webhook-endpoint>
Инспекция HTTP-запросов
При работе с вебхуками рекомендуется использовать такие инструменты, как RequestBin и Requestly. Эти инструменты позволяют инспектировать ваши HTML-запросы, полезные нагрузки ответов и заголовки ответов, чтобы вы могли отлаживать и тестировать вебхуки перед их интеграцией в ваши системы.
Примеры JSON-пакетов
Пример пакета вебхука для запуска, который начался:
{
"accountId": 1,
"webhookId": "wsu_12345abcde",
"eventId": "wev_2L6Z3l8uPedXKPq9D2nWbPIip7Z",
"timestamp": "2023-01-31T19:28:15.742843678Z",
"eventType": "job.run.started",
"webhookName": "test",
"data": {
"jobId": "123",
"jobName": "Daily Job (dbt build)",
"runId": "12345",
"environmentId": "1234",
"environmentName": "Production",
"dbtVersion": "1.0.0",
"projectName": "Snowflake Github Demo",
"projectId": "167194",
"runStatus": "Running",
"runStatusCode": 3,
"runStatusMessage": "None",
"runReason": "Kicked off from the UI by test@test.com",
"runStartedAt": "2023-01-31T19:28:07Z"
}
}
Пример пакета вебхука для завершенного запуска:
{
"accountId": 1,
"webhookId": "wsu_12345abcde",
"eventId": "wev_2L6ZDoilyiWzKkSA59Gmc2d7FDD",
"timestamp": "2023-01-31T19:29:35.789265936Z",
"eventType": "job.run.completed",
"webhookName": "test",
"data": {
"jobId": "123",
"jobName": "Daily Job (dbt build)",
"runId": "12345",
"environmentId": "1234",
"environmentName": "Production",
"dbtVersion": "1.0.0",
"projectName": "Snowflake Github Demo",
"projectId": "167194",
"runStatus": "Success",
"runStatusCode": 10,
"runStatusMessage": "None",
"runReason": "Kicked off from the UI by test@test.com",
"runStartedAt": "2023-01-31T19:28:07Z",
"runFinishedAt": "2023-01-31T19:29:32Z"
}
}
Пример пакета вебхука для запуска с ошибкой:
{
"accountId": 1,
"webhookId": "wsu_12345abcde",
"eventId": "wev_2L6m5BggBw9uPNuSmtg4MUiW4Re",
"timestamp": "2023-01-31T21:15:20.419714619Z",
"eventType": "job.run.errored",
"webhookName": "test",
"data": {
"jobId": "123",
"jobName": "dbt Vault",
"runId": "12345",
"environmentId": "1234",
"environmentName": "dbt Vault Demo",
"dbtVersion": "1.0.0",
"projectName": "Snowflake Github Demo",
"projectId": "167194",
"runStatus": "Errored",
"runStatusCode": 20,
"runStatusMessage": "None",
"runReason": "Kicked off from the UI by test@test.com",
"runStartedAt": "2023-01-31T21:14:41Z",
"runErroredAt": "2023-01-31T21:15:20Z"
}
}
API для вебхуков
Вы можете использовать API dbt для создания новых вебхуков, на которые вы хотите подписаться, получения подробной информации о ваших вебхуках, а также для управления вебхуками, связанными с вашей учетной записью. В следующих разделах описаны конечные точки API, которые вы можете для этого использовать.
dbt размещён в нескольких регионах по всему миру, и для каждого региона используется свой URL доступа. Пользователи тарифных планов Enterprise могут выбрать размещение своей учетной записи в любом из этих регионов. Полный список доступных URL доступа dbt см. в разделе Regions & IP addresses.
Список всех подписок на вебхуки
Отображает список всех вебхуков, доступных для конкретной учетной записи dbt.
Запрос
GET https://{your access URL}/api/v3/accounts/{account_id}/webhooks/subscriptions
Параметры пути
| Loading table... |
Пример ответа
{
"data": [
{
"id": "wsu_12345abcde",
"account_identifier": "act_12345abcde",
"name": "Webhook for jobs",
"description": "A webhook for when jobs are started",
"job_ids": [
"123",
"321"
],
"event_types": [
"job.run.started"
],
"client_url": "https://test.com",
"active": true,
"created_at": "1675735768491774",
"updated_at": "1675787482826757",
"account_id": "123",
"http_status_code": "0"
},
{
"id": "wsu_12345abcde",
"account_identifier": "act_12345abcde",
"name": "Notification Webhook",
"description": "Webhook used to trigger notifications in Slack",
"job_ids": [],
"event_types": [
"job.run.completed",
"job.run.started",
"job.run.errored"
],
"client_url": "https://test.com",
"active": true,
"created_at": "1674645300282836",
"updated_at": "1675786085557224",
"http_status_code": "410",
"dispatched_at": "1675786085548538",
"account_id": "123"
}
],
"status": {
"code": 200
},
"extra": {
"pagination": {
"total_count": 2,
"count": 2
},
"filters": {
"offset": 0,
"limit": 10
}
}
}
Схема ответа
| Loading table... |
Получение подробной информации о вебхуке
Получите подробную информацию о конкретном вебхуке.
Запрос
GET https://{your access URL}/api/v3/accounts/{account_id}/webhooks/subscription/{webhook_id}
Параметры пути
| Loading table... |
Пример ответа
{
"data": {
"id": "wsu_12345abcde",
"account_identifier": "act_12345abcde",
"name": "Webhook for jobs",
"description": "A webhook for when jobs are started",
"event_types": [
"job.run.started"
],
"client_url": "https://test.com",
"active": true,
"created_at": "1675789619690830",
"updated_at": "1675793192536729",
"dispatched_at": "1675793192533160",
"account_id": "123",
"job_ids": [],
"http_status_code": "0"
},
"status": {
"code": 200
}
}
Схема ответа
| Loading table... |
Создание новой подписки на вебхук
Создайте новый исходящий вебхук и укажите URL-адрес конечной точки, который будет подписываться (слушать) на события вебхука.
Пример запроса
POST https://{your access URL}/api/v3/accounts/{account_id}/webhooks/subscriptions
{
"event_types": [
"job.run.started"
],
"name": "Webhook for jobs",
"client_url": "https://test.com",
"active": true,
"description": "A webhook for when jobs are started",
"job_ids": [
123,
321
]
}
Параметры пути
| Loading table... |
Параметры запроса
| Loading table... |
Пример ответа
{
"data": {
"id": "wsu_12345abcde",
"account_identifier": "act_12345abcde",
"name": "Webhook for jobs",
"description": "A webhook for when jobs are started",
"job_ids": [
"123",
"321"
],
"event_types": [
"job.run.started"
],
"client_url": "https://test.com",
"hmac_secret": "12345abcde",
"active": true,
"created_at": "1675795644808877",
"updated_at": "1675795644808877",
"account_id": "123",
"http_status_code": "0"
},
"status": {
"code": 201
}
}
Схема ответа
| Loading table... |
Обновление вебхука
Обновите детали конфигурации для конкретного вебхука.
Пример запроса
PUT https://{your access URL}/api/v3/accounts/{account_id}/webhooks/subscription/{webhook_id}
{
"event_types": [
"job.run.started"
],
"name": "Webhook for jobs",
"client_url": "https://test.com",
"active": true,
"description": "A webhook for when jobs are started",
"job_ids": [
123,
321
]
}
Параметры пути
| Loading table... |
Параметры запроса
| Loading table... |
Пример ответа
{
"data": {
"id": "wsu_12345abcde",
"account_identifier": "act_12345abcde",
"name": "Webhook for jobs",
"description": "A webhook for when jobs are started",
"job_ids": [
"123"
],
"event_types": [
"job.run.started"
],
"client_url": "https://test.com",
"active": true,
"created_at": "1675798888416144",
"updated_at": "1675804719037018",
"http_status_code": "200",
"account_id": "123"
},
"status": {
"code": 200
}
}
Схема ответа
| Loading table... |
Тестирование вебхука
Протестируйте конкретный вебхук.
Запрос
GET https://{your access URL}/api/v3/accounts/{account_id}/webhooks/subscription/{webhook_id}/test
Параметры пути
| Loading table... |
Пример ответа
{
"data": {
"verification_error": null,
"verification_status_code": "200"
},
"status": {
"code": 200
}
}
Удаление вебхука
Удалите конкретный вебхук.
Запрос
DELETE https://{your access URL}/api/v3/accounts/{account_id}/webhooks/subscription/{webhook_id}
Параметры пути
| Loading table... |
Пример ответа
{
"data": {
"id": "wsu_12345abcde"
},
"status": {
"code": 200,
"is_success": true
}
}
Связанная документация
Устранение неполадок
Если ваша целевая система не получает вебхуки dbt, убедитесь, что она поддерживает заголовки Authorization. Вебхуки dbt отправляют заголовок Authorization, и если ваш endpoint не умеет его обрабатывать, он может быть несовместим. Такие сервисы, как Azure Logic Apps и Power Automate, могут не принимать заголовки Authorization, поэтому они не будут работать с вебхуками dbt. Вы можете проверить, поддерживает ли ваш endpoint такие заголовки, отправив запрос с помощью curl с заголовком Authorization, например так:
curl -H 'Authorization: 123' -X POST https://<your-webhook-endpoint>