Webhook のリファレンス

1+ year ago2 min read
Last updated • Read time
クラウド
This document is applicable to CircleCI クラウド
Server v4.x
This document is applicable to CircleCI Server v4.x
Server v3.x
This document is applicable to CircleCI Server v3.x

Webhook の共通のトップレベルキー

イベントの一部として、各Webhook に共通するデータがあります。

フィールド説明タイプ

id

システムからの各イベントを一意に識別するための ID (クライアントはこれを使って重複するイベントを削除できます。 )

文字列

happened_at

イベントが発生した日時を表す ISO 8601 形式のタイムスタンプ

文字列

webhook

トリガーされた Webhook を表すメタデータのマップ

マップ

Webhook の共通のサブエンティティ

ここでは CicrcleCI の Webhook が提供する様々なイベントのペイロードについて説明します。 これらのWebhookイベントのスキーマは、しばしば他のWebhookとデータを共有します。 これらのデータの共通マップは、"サブエンティティ"(sub-entities)として参照されます。 例えば、job-completed 状態の Webhook のイベントペイロードを受信した場合、それにはご自身のプロジェクト、組織、ジョブ、ワークフロー、およびパイプライン のデータマップが含まれます。

様々な Webhook にまたがって現れる、いくつかの共通のサブエンティティについて、以下のセクションで説明します:

プロジェクト

Webhook イベントに関連するプロジェクトに関する以下のデータが提供されます:

フィールド常に表示説明

id

プロジェクトの一意の ID

slug

多くの CircleCI の API の中で特定のプロジェクト(例えば、gh/circleci/web-ui)を参照するために使用する文字列

name

プロジェクトの名前(例:web-ui

組織

webhook イベントに関連する組織に関する以下のデータが提供されます:

フィールド常に表示説明

id

組織の一意の ID

name

組織名 (例:CircleCI)

ジョブ

通常、CircleCI のワークロードにおけるある期間を表し(例:「ビルド」、「テスト」、または「デプロイ」)、一連のステップを含む ジョブ

Webhook イベントに関連するジョブに関する以下のデータが提供されます:

フィールド常に表示説明

id

ジョブの一意の ID

number

ジョブの自動インクリメント番号。 CircleCI の API でプロジェクト内のジョブを識別するために使用される場合があります。

name

.circleci/config.yml で定義されているジョブ名

status

ジョブの現在の状態

started_at

ジョブの実行が開始された時間

stopped_at

×

ワークフローが終了状態になった時間(該当する場合)

ワークフロー

ワークフローはジョブをオーケストレーションします。 Webhookイベントに関連するワークフローについて、以下のデータが提供されます:

フィールド常に表示説明

id

はい

ワークフローの一意の ID

name

はい

.circleci/config.yml で定義されているワークフロー名

status

いいえ

ワークフローの現在の状態。 ジョブレベルの Webhook には含まれません。

created\_at

はい

ワークフローが作成された時間

stopped_at

いいえ

ワークフローが終了状態になった時間(該当する場合)

url

はい

CircleCI の UI にあるワークフローへの URL

パイプライン

パイプラインは最もハイレベルな作業単位で、ゼロ以上のワークフローが含まれます。 1回の git-push で、常に最大で1つのパイプラインをトリガーします。 パイプラインは API から手動でトリガーすることもできます。

Webhook イベントに関連するパイプラインに関する以下のデータが提供されます:

フィールド常に表示説明

id

はい

グローバルに一意なパイプラインの ID

number

はい

バイプラインの番号(自動インクリメントまたはプロジェクトごとに一意)

created\_at

はい

パイプラインが作成された時間

trigger

はい

このパイプラインが作成された原因に関するメタデータ マップ(以下を参照)

trigger_parameters

いいえ

パイプラインに関するメタデータマップ (以下を参照)

vcs

いいえ

このパイプラインに関連する Git コミットに関するメタデータ マップ(以下を参照)

トリガー

Webhook イベントに関連するトリガーについて、以下のデータを提供します:

フィールド常に表示説明

タイプ

このパイプラインがどのようにトリガーされたか(例:「Webhook」、「API」、「スケジュール」)

トリガーパラメーター

パイプラインに関連付けられたデータ。 GitHub や Bitbucket 以外のプロバイダーに関連付けられたパイプラインに存在します。 GitHub と Bitbucket については、下記の [VCS] を参照してください。

フィールド常に表示説明

circleci

トリガー情報を含むマップ (下記参照)

git

×

パイプラインが VCS プロバイダーに関連付けられている場合に存在するマップ

gitlab

×

パイプラインが Gitlab トリガーに関連付けられている場合に存在するマップ

circleci

フィールド常に表示説明

event_time

パイプラインが作成された日時を表す ISO 8601 形式のタイムスタンプ

event_type

パイプラインをトリガーしたプロバイダーのイベントタイプ (push など)

trigger_type

トリガープロバイダー(例:gitlab

actor_id

×

パイプラインが属する CircleCI ユーザー ID

VCS

フィールド常に表示説明

target_repository_url

×

コミットをビルドするレポジトリへの URL

origin_repository_url

×

コミットが作成されたレポジトリへの URL (フォークされたプルリクエストの場合のみ異なります)

revision

×

ビルドする Git コミット

commit.subject

×

コミットのサブジェクト(コミットメッセージの先頭行) 長いコミットサブジェクトは切り捨てられる場合があります。

commit.body

×

コミットの本文(コミットメッセージの後続の行) 長いコミット本文は切り捨てられる場合があります。

commit.author.name

×

コミットの作成者名

commit.author.email

×

コミットの作成者のメールアドレス

commit.authored\_at

×

コミットが作成された時のタイムスタンプ

commit.committer.name

×

コミットのコミッター名

commit.committer.email

×

コミットのコミッターのメールアドレス

commit.committed_at

×

コミットがコミットされた時のタイムスタンプ

branch

×

ビルドされたブランチ

tag

×

ビルドされたタグ(「ブランチ」と相互排他的)

Webhook ペイロードのサンプル

workflow-completed (GitHub/Bitbucket)

{
  "id": "3888f21b-eaa7-38e3-8f3d-75a63bba8895",
  "type": "workflow-completed",
  "happened_at": "2021-09-01T22:49:34.317Z",
  "webhook": {
    "id": "cf8c4fdd-0587-4da1-b4ca-4846e9640af9",
    "name": "Sample Webhook"
  },
  "project": {
    "id": "84996744-a854-4f5e-aea3-04e2851dc1d2",
    "name": "webhook-service",
    "slug": "github/circleci/webhook-service"
  },
  "organization": {
    "id": "f22b6566-597d-46d5-ba74-99ef5bb3d85c",
    "name": "circleci"
  },
  "workflow": {
    "id": "fda08377-fe7e-46b1-8992-3a7aaecac9c3",
    "name": "build-test-deploy",
    "created_at": "2021-09-01T22:49:03.616Z",
    "stopped_at": "2021-09-01T22:49:34.170Z",
    "url": "https://app.circleci.com/pipelines/github/circleci/webhook-service/130/workflows/fda08377-fe7e-46b1-8992-3a7aaecac9c3",
    "status": "success"
  },
  "pipeline": {
    "id": "1285fe1d-d3a6-44fc-8886-8979558254c4",
    "number": 130,
    "created_at": "2021-09-01T22:49:03.544Z",
    "trigger": {
      "type": "webhook"
    },
    "vcs": {
      "provider_name": "github",
      "origin_repository_url": "https://github.com/circleci/webhook-service",
      "target_repository_url": "https://github.com/circleci/webhook-service",
      "revision": "1dc6aa69429bff4806ad6afe58d3d8f57e25973e",
      "commit": {
        "subject": "Description of change",
        "body": "More details about the change",
        "author": {
          "name": "Author Name",
          "email": "author.email@example.com"
        },
        "authored_at": "2021-09-01T22:48:53Z",
        "committer": {
          "name": "Committer Name",
          "email": "committer.email@example.com"
        },
        "committed_at": "2021-09-01T22:48:53Z"
      },
      "branch": "main"
    }
  }
}

job-completed (GitHub/Bitbucket)

{
  "id": "8bd71c28-4969-3677-8940-3e3a61c46660",
  "type": "job-completed",
  "happened_at": "2021-09-01T22:49:34.279Z",
  "webhook": {
    "id": "cf8c4fdd-0587-4da1-b4ca-4846e9640af9",
    "name": "Sample Webhook"
  },
  "project": {
    "id": "84996744-a854-4f5e-aea3-04e2851dc1d2",
    "name": "webhook-service",
    "slug": "github/circleci/webhook-service"
  },
  "organization": {
    "id": "f22b6566-597d-46d5-ba74-99ef5bb3d85c",
    "name": "circleci"
  },
  "pipeline": {
    "id": "1285fe1d-d3a6-44fc-8886-8979558254c4",
    "number": 130,
    "created_at": "2021-09-01T22:49:03.544Z",
    "trigger": {
      "type": "webhook"
    },
    "vcs": {
      "provider_name": "github",
      "origin_repository_url": "https://github.com/circleci/webhook-service",
      "target_repository_url": "https://github.com/circleci/webhook-service",
      "revision": "1dc6aa69429bff4806ad6afe58d3d8f57e25973e",
      "commit": {
        "subject": "Description of change",
        "body": "More details about the change",
        "author": {
          "name": "Author Name",
          "email": "author.email@example.com"
        },
        "authored_at": "2021-09-01T22:48:53Z",
        "committer": {
          "name": "Committer Name",
          "email": "committer.email@example.com"
        },
        "committed_at": "2021-09-01T22:48:53Z"
      },
      "branch": "main"
    }
  },
  "workflow": {
    "id": "fda08377-fe7e-46b1-8992-3a7aaecac9c3",
    "name": "welcome",
    "created_at": "2021-09-01T22:49:03.616Z",
    "stopped_at": "2021-09-01T22:49:34.170Z",
    "url": "https://app.circleci.com/pipelines/github/circleci/webhook-service/130/workflows/fda08377-fe7e-46b1-8992-3a7aaecac9c3"
  },
  "job": {
    "id": "8b91f9a8-7975-4e60-916c-f0152ccbc937",
    "name": "test",
    "started_at": "2021-09-01T22:49:28.841Z",
    "stopped_at": "2021-09-01T22:49:34.170Z",
    "status": "success",
    "number": 136
  }
}

workflow-completed (Gitlab)

{
  "type": "workflow-completed",
  "id": "cbabbb40-6084-4f91-8311-a326c0f4963a",
  "happened_at": "2022-05-27T16:20:13.954328Z",
  "webhook": {
    "id": "e4da0d23-31cf-4047-8a7e-8ffb14cd0100",
    "name": "test"
  },
  "workflow": {
    "id": "c2006ece-778d-49fc-9e6e-b9965f72bee9",
    "name": "build",
    "created_at": "2022-05-27T16:20:07.631Z",
    "stopped_at": "2022-05-27T16:20:13.812Z",
    "url": "https://app.circleci.com/pipelines/circleci/DdaVtNusHqi24D4YT3X4eu/6EkDPZoN4ZdMKKZtBkRodt/1/workflows/c2006ece-778d-49fc-9e6e-b9965f72bee9",
    "status": "failed"
  },
  "pipeline": {
    "id": "37c74cb7-d64d-4032-8731-1cb95bfef921",
    "number": 1,
    "created_at": "2022-04-13T11:10:18.804Z",
    "trigger": {
      "type": "gitlab"
    },
    "trigger_parameters": {
      "gitlab": {
        "web_url": "https://gitlab.com/circleci/hello-world",
        "commit_author_name": "Commit Author",
        "user_id": "9534789",
        "user_name": "User name",
        "user_username": "username",
        "branch": "main",
        "commit_title": "Update README.md",
        "commit_message": "Update README.md",
        "total_commits_count": "1",
        "repo_url": "git@gitlab.com:circleci/hello-world.git",
        "user_avatar": "https://secure.gravatar.com/avatar",
        "type": "push",
        "project_id": "33852820",
        "ref": "refs/heads/main",
        "repo_name": "hello-world",
        "commit_author_email": "committer.email@example.com",
        "checkout_sha": "850a1519f25d14e968649cc420d1bd381715c05c",
        "commit_timestamp": "2022-04-13T11:10:16+00:00",
        "commit_sha": "850a1519f25d14e968649cc420d1bd381715c05c"
      },
      "git": {
        "tag": "",
        "checkout_sha": "850a1519f25d14e968649cc420d1bd381715c05c",
        "ref": "refs/heads/main",
        "branch": "main",
        "checkout_url": "git@gitlab.com:circleci/hello-world.git"
      },
      "circleci": {
        "event_time": "2022-04-13T11:10:18.349Z",
        "actor_id": "6a19122c-40e0-4d56-a875-aac6ccc27700",
        "event_type": "push",
        "trigger_type": "gitlab"
      }
    }
  },
  "project": {
    "id": "2a68fe5f-2fe5-4d4f-91e1-15f111116743",
    "name": "hello-world",
    "slug": "circleci/DdaVtNusHqi24D4YT3X4eu/6EkDPZoN4ZdMKKZtBkRodt"
  },
  "organization": {
    "id": "66491562-90a9-4065-9249-4b0ce3b77452",
    "name": "circleci"
  }
}

job-completed (Gitlab)

{
  "type": "workflow-completed",
  "id": "47a497be-4498-4da0-a4e8-2dabd889af0f",
  "happened_at": "2022-05-27T16:20:13.954328Z",
  "webhook": {
    "id": "e4da0d23-31cf-4047-8a7e-8ffb14cd0100",
    "name": "test"
  },
  "job": {
    "id": "2fc6977d-7e45-4271-b355-0ea894d82017",
    "name": "say-hello",
    "started_at": "2022-07-11T12:16:37.435Z",
    "stopped_at": "2022-07-11T12:16:59.982Z",
    "status": "success",
    "number": 1
  }
  "pipeline": {
    "id": "37c74cb7-d64d-4032-8731-1cb95bfef921",
    "number": 1,
    "created_at": "2022-04-13T11:10:18.804Z",
    "trigger": {
      "type": "gitlab"
    },
    "trigger_parameters": {
      "gitlab": {
        "web_url": "https://gitlab.com/circleci/hello-world",
        "commit_author_name": "Commit Author",
        "user_id": "9534789",
        "user_name": "User name",
        "user_username": "username",
        "branch": "main",
        "commit_title": "Update README.md",
        "commit_message": "Update README.md",
        "total_commits_count": "1",
        "repo_url": "git@gitlab.com:circleci/hello-world.git",
        "user_avatar": "https://secure.gravatar.com/avatar",
        "type": "push",
        "project_id": "33852820",
        "ref": "refs/heads/main",
        "repo_name": "hello-world",
        "commit_author_email": "committer.email@example.com",
        "checkout_sha": "850a1519f25d14e968649cc420d1bd381715c05c",
        "commit_timestamp": "2022-04-13T11:10:16+00:00",
        "commit_sha": "850a1519f25d14e968649cc420d1bd381715c05c"
      },
      "git": {
        "tag": "",
        "checkout_sha": "850a1519f25d14e968649cc420d1bd381715c05c",
        "ref": "refs/heads/main",
        "branch": "main",
        "checkout_url": "git@gitlab.com:circleci/hello-world.git"
      },
      "circleci": {
        "event_time": "2022-04-13T11:10:18.349Z",
        "actor_id": "6a19122c-40e0-4d56-a875-aac6ccc27700",
        "event_type": "push",
        "trigger_type": "gitlab"
      }
    }
  },
  "project": {
    "id": "2a68fe5f-2fe5-4d4f-91e1-15f111116743",
    "name": "hello-world",
    "slug": "circleci/DdaVtNusHqi24D4YT3X4eu/6EkDPZoN4ZdMKKZtBkRodt"
  },
  "organization": {
    "id": "66491562-90a9-4065-9249-4b0ce3b77452",
    "name": "circleci"
  }
}

次のステップ