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

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

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

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

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

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

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

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

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

Видео

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

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

Предварительные условия

  • У вас есть учетная запись dbt Cloud на плане Team или Enterprise.
  • Для доступа write к вебхукам:
    • Учетные записи плана Enterprise — Наборы разрешений одинаковы как для токенов службы API, так и для интерфейса dbt Cloud. Вы или токен службы API должны иметь набор разрешений Account Admin, Admin или Developer permission set.
    • Учетные записи плана Team — Для интерфейса dbt Cloud вам необходимо иметь лицензию разработчика. Для токенов службы API вы должны назначить токен службы, чтобы иметь набор разрешений Account Admin или Member.
  • У вас есть многопользовательская или одноарендная модель развертывания AWS в dbt Cloud. Для получения дополнительной информации обратитесь к Многопользовательской среде.
  • Ваша система назначения поддерживает заголовки авторизации.

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

Перейдите в Настройки учетной записи в dbt Cloud (нажав на имя вашей учетной записи в левой панели) и нажмите Создать новый вебхук в разделе Вебхуки. Вы можете найти соответствующий URL-адрес доступа dbt Cloud для вашего региона и плана с помощью Регионы и IP-адреса.

Чтобы настроить новый вебхук:

  • Имя — Введите имя для вашего исходящего вебхука.
  • Описание — Введите описание вебхука.
  • События — Выберите событие, которое вы хотите использовать для запуска этого вебхука. Вы можете подписаться на более чем одно событие.
  • Задачи — Укажите задачу(и), на которые вы хотите, чтобы вебхук срабатывал. Или вы можете оставить это поле пустым, чтобы вебхук срабатывал на все задачи в вашей учетной записи. По умолчанию dbt Cloud настраивает ваш вебхук на уровне учетной записи.
  • Конечная точка — Введите URL-адрес конечной точки вашего приложения, куда dbt Cloud может отправлять событие(я).

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

Различия между завершенными и ошибочными событиями вебхуков

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

  • job.run.completed — Это событие срабатывает только после того, как метаданные и артефакты задачи были загружены и доступны из API dbt Cloud Admin и Discovery.
  • job.run.errored — Это событие срабатывает немедленно, поэтому метаданные и артефакты задачи могут не быть загружены. Это означает, что информация может быть недоступна для использования.

Если ваша интеграция зависит от данных из Admin API (например, доступ к журналам запуска) или Discovery API (доступ к статусам моделей), используйте событие job.run.completed и фильтруйте по runStatus или runStatusCode.

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

Проверка вебхука

Вы можете использовать секретный токен, предоставленный dbt Cloud, чтобы проверить, что вебхуки, полученные вашей конечной точкой, действительно были отправлены dbt Cloud. Официальные вебхуки будут включать заголовок 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,
"webhooksID": "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 UI by test@test.com",
"runStartedAt": "2023-01-31T19:28:07Z"
}
}

Пример пакета вебхука для завершенного запуска:

{
"accountId": 1,
"webhooksID": "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 UI by test@test.com",
"runStartedAt": "2023-01-31T19:28:07Z",
"runFinishedAt": "2023-01-31T19:29:32Z"
}
}

Пример пакета вебхука для запуска с ошибкой:

{
"accountId": 1,
"webhooksID": "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 UI by test@test.com",
"runStartedAt": "2023-01-31T21:14:41Z",
"runErroredAt": "2023-01-31T21:15:20Z"
}
}

API для вебхуков

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

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

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

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

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

Запрос

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

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

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

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

{
"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 Cloud.
idID вебхука. Это универсальный уникальный идентификатор (UUID), уникальный для всех регионов, включая многопользовательские и одноарендные.
account_identifierУникальный идентификатор для вашей учетной записи dbt Cloud.
nameИмя исходящего вебхука.
descriptionОписание вебхука.
job_idsКонкретные задачи, для которых настроен вебхук. Когда список пуст, вебхук настроен для срабатывания на все задачи в вашей учетной записи; по умолчанию dbt Cloud настраивает вебхуки на уровне учетной записи.
  • Пустой список
  • Список ID задач
event_typesТип(ы) события, на которые настроен вебхук.Один или несколько из следующих:
  • job.run.started
  • job.run.completed
  • job.run.errored
client_urlURL-адрес конечной точки для приложения, куда dbt Cloud может отправлять событие(я).
activeЛогическое значение, указывающее, активен ли вебхук.Одно из следующих:
  • true
  • false
created_atВременная метка создания вебхука.
updated_atВременная метка последнего обновления вебхука.
http_status_codeПоследний HTTP-статус вебхука.Может быть любым кодом состояния HTTP-ответа. Если значение 0, это означает, что вебхук никогда не срабатывал.
dispatched_atВременная метка последней отправки вебхука на указанную конечную точку.
account_idID учетной записи dbt Cloud.

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

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

Запрос

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

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

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

Схема ответа

ИмяОписаниеВозможные значения
idID вебхука.
account_identifierУникальный идентификатор для вашей учетной записи dbt Cloud.
nameИмя исходящего вебхука.
descriptionПолное описание вебхука.
event_typesТип события, на которое настроен вебхук.Один или несколько из следующих:
  • job.run.started
  • job.run.completed
  • job.run.errored
client_urlURL-адрес конечной точки для приложения, куда dbt Cloud может отправлять событие(я).
activeЛогическое значение, указывающее, активен ли вебхук.Одно из следующих:
  • true
  • false
created_atВременная метка создания вебхука.
updated_atВременная метка последнего обновления вебхука.
dispatched_atВременная метка последней отправки вебхука на указанную конечную точку.
account_idID учетной записи dbt Cloud.
job_idsКонкретные задачи, для которых настроен вебхук. Когда список пуст, вебхук настроен для срабатывания на все задачи в вашей учетной записи; по умолчанию dbt Cloud настраивает вебхуки на уровне учетной записи.Один из следующих:
  • Пустой список
  • Список ID задач
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 Cloud.
account_idУчетная запись dbt Cloud, с которой связан вебхук.

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

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

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

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

Схема ответа

ИмяОписаниеВозможные значения
idID вебхука.
account_identifierУникальный идентификатор для вашей учетной записи dbt Cloud.
nameИмя исходящего вебхука.
descriptionПолное описание вебхука.
job_idsКонкретные задачи, для которых настроен вебхук. Когда список пуст, вебхук настроен для срабатывания на все задачи в вашей учетной записи; по умолчанию dbt Cloud настраивает вебхуки на уровне учетной записи.Один из следующих:
  • Пустой список
  • Список ID задач
event_typesТип события, на которое настроен вебхук.Один или несколько из следующих:
  • job.run.started
  • job.run.completed
  • job.run.errored
client_urlURL-адрес конечной точки для приложения, куда dbt Cloud может отправлять событие(я).
hmac_secretСекретный ключ для вашего нового вебхука. Вы можете использовать этот ключ для проверки подлинности этого вебхука.
activeЛогическое значение, указывающее, активен ли вебхук.Одно из следующих:
  • true
  • false
created_atВременная метка создания вебхука.
updated_atВременная метка последнего обновления вебхука.
account_idID учетной записи dbt Cloud.
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 Cloud.
account_idУчетная запись dbt Cloud, с которой связан вебхук.
webhook_idВебхук, который вы хотите обновить.

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

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

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

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

Схема ответа

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

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

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

Запрос

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

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

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

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

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

Связанные документы

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

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

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