Перейти к основному содержимому

Вебхуки для ваших заданий

С помощью dbt вы можете создавать исходящие вебхуки для отправки событий (уведомлений) о ваших заданиях dbt в другие системы. Эти системы могут отслеживать такие события (подписываться на них), чтобы дополнительно автоматизировать ваши рабочие процессы или запускать настроенные вами сценарии автоматизации.

Вебхук — это функция обратного вызова на основе HTTP, которая позволяет осуществлять коммуникацию, основанную на событиях, между двумя различными веб-приложениями. Это позволяет получать самую актуальную информацию о ваших задачах dbt в реальном времени. Без этого вам пришлось бы многократно делать вызовы API, чтобы проверить, есть ли какие-либо обновления, которые вам нужно учесть (опрос). Из-за этого вебхуки также называют push API или reverse API и часто используют для разработки инфраструктуры.

dbt отправляет JSON-данные на URL-адрес конечной точки вашего приложения при срабатывании вебхука. Вы можете отправить уведомление в Slack, уведомление в Microsoft Teams или создать инцидент в PagerDuty, если задание dbt завершится с ошибкой.

Вы можете создавать вебхуки для этих событий через веб-интерфейс dbt и с помощью API dbt:

  • job.run.started — Запуск начат.
  • job.run.completed — Запуск завершен. Это может быть запуск, который завершился с ошибкой или успешно.
  • job.run.errored — Запуск завершился с ошибкой.

dbt делает до пяти повторных попыток отправки каждого события. dbt хранит журнал доставки каждого вебхука в течение 7 дней. У каждого вебхука есть собственный раздел Recent Deliveries, в котором можно сразу увидеть, была ли доставка успешной или завершилась сбоем.

Тайм-аут вебхука в dbt составляет 10 секунд. Это означает, что если конечная точка не отвечает в течение 10 секунд, обработчик вебхуков прекращает ожидание. В результате может возникнуть ситуация, когда клиент успешно отвечает по истечении 10-секундного тайм-аута и регистрирует успешный статус, а система вебхуков dbt считает доставку неудачной.

Видео

Если вас интересует обучение с помощью видео, ознакомьтесь с курсом по вебхукам на требование от dbt Labs.

Вы также можете ознакомиться с бесплатным курсом Основы dbt.

Предварительные требования​

  • У вас есть учетная запись dbt на тарифном плане Starter или Enterprise.
  • Для доступа к вебхукам с правом write:
    • Тарифные планы Enterprise — Наборы разрешений одинаковы для сервисных токенов API и пользовательского интерфейса dbt. У вас или у сервисного токена API должен быть набор разрешений Account Admin, Admin или Developer.
    • Учетные записи на тарифном плане Starter — Для работы в пользовательском интерфейсе (UI) dbt вам нужна лицензия Developer.
  • Вы используете многопользовательскую (multi-tenant) или однопользовательскую (single-tenant) модель развертывания на AWS в dbt. Подробнее см. в разделе Модель размещения.
  • Ваша целевая система поддерживает заголовки Authorization.

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

  1. Перейдите в Account settings в dbt (нажмите на название своей учетной записи на левой боковой панели)

  2. Перейдите в раздел Webhooks и нажмите Create webhook.

  3. Настройте новый вебхук:

    • Webhook name — Введите имя исходящего вебхука.
    • Description — Введите описание вебхука.
    • Events — Выберите событие, которое должно вызывать срабатывание этого вебхука. Можно подписаться на несколько событий.
    • Jobs — Укажите задания, для которых должен срабатывать вебхук. Также можно оставить это поле пустым, чтобы вебхук срабатывал для всех заданий в вашей учетной записи. По умолчанию dbt настраивает вебхук на уровне учетной записи.
    • Endpoint — Введите URL конечной точки вашего приложения, на который dbt сможет отправлять события.
  4. По завершении нажмите Save.

    dbt предоставляет секретный токен, который можно использовать для проверки подлинности вебхука. Настоятельно рекомендуется выполнять эту проверку на вашем сервере, чтобы защититься от поддельных запросов (спуфинга).

Архивированные вебхуки​

dbt автоматически архивирует вебхук после 1 000 неудачных попыток доставки подряд или 7 дней подряд с неудачными попытками доставки — в зависимости от того, что наступит раньше.

  • На странице Account settings → Webhooks в dbt platform появляется предупреждающий баннер, который можно закрыть, если одна или несколько подписок архивированы.
  • У архивированных подписок в столбце статуса вместо HTTP-статуса отображается значок Archived.
  • Наведите указатель на значок, чтобы узнать, почему dbt архивировал подписку и как ее повторно активировать.
Страница вебхуков с предупреждающим баннером об архивированной подписке и значком статуса «Archived»Страница вебхуков с предупреждающим баннером об архивированной подписке и значком статуса «Archived»

Чтобы повторно активировать вебхук, воспользуйтесь одним из следующих способов:

  • Пользовательский интерфейс dbt platform: Измените URL конечной точки вебхука. dbt автоматически повторно активирует вебхук при изменении URL.
  • REST API: Отправьте запрос PUT для обновления вебхука и задайте для active значение true или укажите в client_url новый URL конечной точки.
  • Провайдер Terraform: Задайте active = true и обновите client_url в ресурсе вебхука.

Чтобы найти подходящий URL доступа к dbt для вашего региона и тарифного плана, обратитесь к разделу Регионы и IP-адреса.

Различия между событиями вебхуков completed и errored​

Событие job.run.errored — это частный случай событий job.run.completed. Если вы подпишетесь на оба события, то получите два уведомления при возникновении ошибки в задании. Однако dbt инициирует эти два события в разные моменты:

  • job.run.completed — Это событие возникает только после того, как метаданные и артефакты задания будут загружены и станут доступны через Admin API и 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, которые можно использовать для этого.

URL-адреса доступа

dbt размещается в нескольких регионах мира, и у каждого региона свой URL-адрес доступа. Пользователи тарифных планов Enterprise могут выбрать любой из этих регионов для размещения своей учетной записи. Полный список доступных URL-адресов доступа к dbt приведен в разделе Регионы и IP-адреса.

Получение списка всех подписок на вебхуки​

Получите список всех вебхуков, доступных в определенной учетной записи dbt.

Запрос​

GET https://{your access URL}/api/v3/accounts/{account_id}/webhooks/subscriptions

Параметры пути​

ИмяОписание
your access URLURL для входа в вашу учетную запись dbt.
account_idУчетная запись dbt, с которой связаны вебхуки.

Пример ответа​

{
"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
}
}
}

Схема ответа​

ИмяОписаниеВозможные значения
dataСписок доступных вебхуков для указанного идентификатора аккаунта dbt.
idИдентификатор вебхука. Это универсальный уникальный идентификатор (UUID), уникальный во всех регионах, включая мультитенантные и однотенантные среды.
account_identifierУникальный идентификатор вашего аккаунта dbt.
nameНазвание исходящего вебхука.
descriptionОписание вебхука.
job_idsКонкретные задания, для которых настроено срабатывание вебхука. Если список пуст, вебхук настроен на срабатывание для всех заданий в вашем аккаунте; по умолчанию dbt настраивает вебхуки на уровне аккаунта.
  • Пустой список
  • Список идентификаторов заданий
event_typesТипы событий, при которых настроено срабатывание вебхука.Один или несколько из следующих типов:
  • job.run.started
  • job.run.completed
  • job.run.errored
client_urlURL конечной точки приложения, на который dbt может отправлять события.
activeЛогическое значение, указывающее, активен ли вебхук.Одно из следующих значений:
  • true
  • false
created_atОтметка времени создания вебхука.
updated_atОтметка времени последнего обновления вебхука.
http_status_codeПоследний код состояния HTTP для вебхука.Может быть любым кодом состояния ответа HTTP. Значение 0 означает, что вебхук ни разу не срабатывал.
dispatched_atОтметка времени последней отправки вебхука на указанный URL конечной точки.
account_idИдентификатор аккаунта dbt.

Получение подробной информации о вебхуке​

Получите подробную информацию о конкретном вебхуке.

Запрос​

GET https://{your access URL}/api/v3/accounts/{account_id}/webhooks/subscription/{webhook_id}

Параметры пути​

ИмяОписание
your access URLURL для входа в вашу учетную запись dbt.
account_idУчетная запись dbt, с которой связан вебхук.
webhook_idВебхук, о котором вы хотите получить подробную информацию.

Пример ответа​

{
"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
}
}

Схема ответа​

ИмяОписаниеВозможные значения
idИдентификатор вебхука.
account_identifierУникальный идентификатор вашей учетной записи dbt.
nameНазвание исходящего вебхука.
descriptionПолное описание вебхука.
event_typesТип события, при котором настроено срабатывание вебхука.Один или несколько из следующих типов:
  • job.run.started
  • job.run.completed
  • job.run.errored
client_urlURL конечной точки приложения, на который dbt может отправлять события.
activeЛогическое значение, указывающее, активен ли вебхук.Одно из следующих значений:
  • true
  • false
created_atМетка времени создания вебхука.
updated_atМетка времени последнего обновления вебхука.
dispatched_atМетка времени последней отправки вебхука на указанный URL конечной точки.
account_idИдентификатор учетной записи dbt.
job_idsКонкретные задания, для которых настроено срабатывание вебхука. Если список пуст, вебхук настроен на срабатывание для всех заданий в вашей учетной записи; по умолчанию dbt настраивает вебхуки на уровне учетной записи.Один из следующих вариантов:
  • Пустой список
  • Список идентификаторов заданий
http_status_codeПоследний код состояния HTTP для вебхука.Может быть любым кодом состояния ответа HTTP. Если значение равно 0, это означает, что вебхук еще ни разу не срабатывал.

Создание новой подписки на вебхук​

Создайте новый исходящий вебхук и укажите 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
]
}

Параметры пути​

ИмяОписание
your access URLURL для входа в вашу учетную запись dbt.
account_idУчетная запись dbt, с которой связан вебхук.

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

ИмяОписаниеВозможные значения
event_typesУкажите событие, которое должно вызывать срабатывание этого вебхука. Вы можете подписаться на несколько событий.Одно или несколько из следующих событий:
  • job.run.started
  • job.run.completed
  • job.run.errored
nameУкажите имя вашего вебхука.
client_urlУкажите URL конечной точки вашего приложения, на который dbt сможет отправлять события.
activeУкажите логическое значение, определяющее, активен ли ваш вебхук.Одно из следующих значений:
  • true
  • false
descriptionУкажите описание вашего вебхука.
job_idsУкажите конкретные задания, для которых должен срабатывать вебхук, или оставьте этот параметр пустым списком. Если список пуст, вебхук будет срабатывать для всех заданий в вашей учётной записи; по умолчанию dbt настраивает вебхуки на уровне учётной записи.Один из следующих вариантов:
  • Пустой список
  • Список идентификаторов заданий

Пример ответа​

{
"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
}
}

Схема ответа​

ИмяОписаниеВозможные значения
idИдентификатор вебхука.
account_identifierУникальный идентификатор вашей учетной записи dbt.
nameНазвание исходящего вебхука.
descriptionПолное описание вебхука.
job_idsКонкретные задания, для которых настроено срабатывание вебхука. Если список пуст, вебхук настроен на срабатывание для всех заданий в вашей учетной записи; по умолчанию dbt настраивает вебхуки на уровне учетной записи.Один из вариантов:
  • Пустой список
  • Список идентификаторов заданий
event_typesТип события, при котором настроено срабатывание вебхука.Один или несколько из следующих вариантов:
  • job.run.started
  • job.run.completed
  • job.run.errored
client_urlURL конечной точки приложения, на которую dbt может отправлять события.
hmac_secretСекретный ключ для вашего нового вебхука. Этот ключ можно использовать для проверки подлинности этого вебхука.
activeЛогическое значение, указывающее, активен ли вебхук.Один из вариантов:
  • true
  • false
created_atМетка времени создания вебхука.
updated_atМетка времени последнего обновления вебхука.
account_idИдентификатор учетной записи dbt.
http_status_codeПоследний код состояния HTTP вебхука.Может быть любым кодом состояния ответа HTTP. Если значение равно 0, это означает, что вебхук еще ни разу не срабатывал.

Обновление вебхука​

Обновите детали конфигурации для конкретного вебхука.

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

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
]
}

Параметры пути​

ИмяОписание
your access URLURL для входа в вашу учетную запись dbt.
account_idУчетная запись dbt, с которой связан вебхук.
webhook_idВебхук, который вы хотите обновить.

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

ИмяОписаниеВозможные значения
event_typesИзмените тип события, при котором срабатывает вебхук. Можно подписаться на несколько типов событий.Один или несколько из следующих типов:
  • job.run.started
  • job.run.completed
  • job.run.errored
nameИзмените имя вебхука.
client_urlОбновите URL конечной точки приложения, на которую dbt может отправлять события.
activeИзмените логическое значение, указывающее, активен ли вебхук.Одно из следующих значений:
  • true
  • false
descriptionОбновите описание вебхука.
job_idsИзмените список заданий, для которых должен срабатывать вебхук. Также можно использовать пустой список, чтобы вебхук срабатывал для всех заданий в вашем аккаунте.Один из следующих вариантов:
  • Пустой список
  • Список идентификаторов заданий

Пример ответа​

{
"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
}
}

Схема ответа​

ИмяОписаниеВозможные значения
idИдентификатор вебхука.
account_identifierУникальный идентификатор вашего аккаунта dbt.
nameНазвание исходящего вебхука.
descriptionПолное описание вебхука.
job_idsКонкретные задания, для которых настроено срабатывание вебхука. Если список пуст, вебхук настроен на срабатывание для всех заданий в вашем аккаунте; по умолчанию dbt настраивает вебхуки на уровне аккаунта.Один из вариантов:
  • Пустой список
  • Список идентификаторов заданий
event_typesТип события, при котором срабатывает вебхук.Один или несколько из следующих типов:
  • job.run.started
  • job.run.completed
  • job.run.errored
client_urlURL конечной точки приложения, на которую dbt может отправлять события.
activeЛогическое значение, указывающее, активен ли вебхук.Одно из значений:
  • true
  • false
created_atВременная метка создания вебхука.
updated_atВременная метка последнего обновления вебхука.
http_status_codeПоследний код состояния HTTP для вебхука.Может быть любым кодом состояния ответа HTTP. Если значение равно 0, это означает, что вебхук ещё ни разу не срабатывал.
account_idИдентификатор аккаунта dbt.

Тестирование вебхука​

Протестируйте конкретный вебхук.

Запрос​

GET https://{your access URL}/api/v3/accounts/{account_id}/webhooks/subscription/{webhook_id}/test

Параметры пути​

ИмяОписание
your access URLURL для входа в вашу учетную запись dbt.
account_idУчетная запись dbt, с которой связан вебхук.
webhook_idВебхук, который вы хотите протестировать.

Пример ответа​

{
"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}

Параметры пути​

ИмяОписание
your access URLURL для входа в вашу учетную запись dbt.
account_idУчетная запись dbt, с которой связан вебхук.
webhook_idВебхук, который вы хотите удалить.

Пример ответа​

{
"data": {
"id": "wsu_12345abcde"
},
"status": {
"code": 200,
"is_success": true
}
}

Связанная документация​

Устранение неполадок​

Если ваша целевая система не получает вебхуки dbt, убедитесь, что она допускает заголовки Authorization. Вебхуки dbt отправляют заголовок Authorization, и если ваш эндпоинт не поддерживает его, он может быть несовместим с ними. Такие сервисы, как Azure Logic Apps и Power Automate, могут не принимать заголовки Authorization, поэтому они не будут работать с вебхуками dbt. Вы можете проверить, поддерживает ли ваш эндпоинт этот заголовок, отправив запрос с помощью curl с заголовком Authorization, например так:

curl -H 'Authorization: 123' -X POST https://<your-webhook-endpoint>

Нашли ошибку?

0
Loading