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

Вебхуки для ваших заданий 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.

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

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

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

  3. Для настройки нового вебхука:

    • Webhook name — Введите имя для исходящего вебхука.
    • Description — Введите описание вебхука.
    • Events — Выберите событие, при наступлении которого будет срабатывать этот вебхук. Можно подписаться на несколько событий.
    • Jobs — Укажите задание(я), для которых должен срабатывать вебхук. Либо оставьте это поле пустым, чтобы вебхук срабатывал для всех заданий в вашей учетной записи. По умолчанию dbt настраивает вебхук на уровне учетной записи.
    • Endpoint — Укажите URL эндпоинта вашего приложения, на который dbt сможет отправлять события.
  4. По завершении нажмите 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, которые вы можете для этого использовать.

URLs доступа

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

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

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

Запрос

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

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

ИмяОписание
your access URLURL для входа в вашу учётную запись dbt.
account_idУчётная запись dbt, с которой связаны вебхуки.
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
}
}
}

Схема ответа

ИмяОписаниеВозможные значения
dataСписок доступных вебхуков для указанного ID аккаунта dbt.
idID вебхука. Это универсально уникальный идентификатор (UUID), который является уникальным для всех регионов, включая multi-tenant и single-tenant.
account_identifierУникальный идентификатор вашего аккаунта dbt.
nameИмя исходящего вебхука.
descriptionОписание вебхука.
job_idsКонкретные job’ы, для которых настроен запуск вебхука. Если список пуст, вебхук будет срабатывать для всех job’ов в вашем аккаунте; по умолчанию dbt настраивает вебхуки на уровне аккаунта.
  • Пустой список
  • Список ID job’ов
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_idID аккаунта dbt.
Loading table...

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

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

Запрос

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

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

ИмяОписание
your access URLURL для входа в вашу учетную запись dbt.
account_idУчетная запись dbt, с которой связан вебхук.
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
}
}

Схема ответа

ИмяОписаниеВозможные значения
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, это означает, что вебхук ни разу не срабатывал.
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
]
}

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

ИмяОписание
your access URLURL для входа в ваш аккаунт dbt.
account_idАккаунт dbt, с которым связан вебхук.
Loading table...

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

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

Схема ответа

ИмяОписаниеВозможные значения
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, это означает, что вебхук ни разу не срабатывал.
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
]
}

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

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

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

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

Схема ответа

ИмяОписаниеВозможные значения
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.
Loading table...

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

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

Запрос

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

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

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

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

ИмяОписание
your access URLURL для входа в вашу учетную запись dbt.
account_idУчетная запись dbt, с которой связан webhook.
webhook_idWebhook, который вы хотите удалить.
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>

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

0
Loading