

この連載では、これまで「こちらから送る」側を自分で書いてきました。curl のコマンドも、Python のスクリプトも、Google Apps Script も、パラメータの名前をデータ項目のフィールド名に合わせて書けます。
外部サービスからの通知は違います。何が起きたかを知らせてくるのは相手で、送る内容の形式も相手が決めています。
この記事では、GitHub でリリースを公開したときに GitHub が送る通知 (Webhook) を受けて、告知のケースを開始します。[メッセージ開始イベント (Webhook)]でリクエストボディをそのまま受け取り、[スクリプトタスク]で解析する、という流れです。

[メッセージ開始イベント (HTTP)]では受けられない理由
[メッセージ開始イベント (HTTP)]が受け付けるのは POST で、Content-Type は application/x-www-form-urlencoded と multipart/form-data です。データ項目に値を入れるパラメータの名前は、データ項目のフィールド名そのもの(q_ で始まる名前)と決まっています。
GitHub の Webhook は、送るときの Content-Type を 2 つから選べます。
- application/json — JSON をそのままリクエストボディとして送ります
- application/x-www-form-urlencoded — 同じ JSON を
payloadという名前のパラメータの値として送ります
前者は Content-Type が合いません。後者は Content-Type は合いますが、パラメータの名前が payload の 1 つで、q_ で始まる名前にはなりません。値も JSON の文字列そのものです。名前も形も GitHub が決めているので、こちらでは変えられません。
[メッセージ開始イベント (Webhook)]は、リクエストボディを解釈せずに、そのまま 1 つのデータ項目に保存します。中身がどういう構造であっても受け取れます。
| [メッセージ開始イベント (HTTP)] | [メッセージ開始イベント (Webhook)] | |
|---|---|---|
| 受け付ける Content-Type | application/x-www-form-urlencoded、multipart/form-data | 設定で指定する。候補として application/json、text/xml、application/x-www-form-urlencoded が表示され、それ以外を直接入力することもできる |
| 受け付ける HTTP メソッド | POST | GET・POST・PUT・PATCH・DELETE から選ぶ |
| データ項目への入り方 | q_ で始まるパラメータごとに、対応するデータ項目へ入る | リクエストボディをまるごと 1 つのデータ項目に保存する |
| 保存された値からの取り出し | 不要 | [スクリプトタスク]で解析する |
| 応答 | ケース ID をテキストで返す(固定) | [HTTP レスポンスの内容]に書いた本文を返せる |
送る側を自分で書けるのであれば、[メッセージ開始イベント (HTTP)]の方が手数は少なくて済みます。解析の工程が要らず、値が直接データ項目に入ります。
作るワークフローアプリ
「リリース告知」という練習用のワークフローアプリを作ります。工程は次のとおりです。
- [メッセージ開始イベント (Webhook)]「GitHub からの通知の受信」
- [スクリプトタスク]「通知の解析」
- [データ更新]「件名の設定」
- [分岐 XOR ゲートウェイ]「公開の通知かどうか」
- [ヒューマンタスク]「告知文の作成」
- [終了イベント]「告知済み」
- [終了イベント]「対象外」
[分岐 XOR ゲートウェイ]「公開の通知かどうか」からは 2 本に分かれます。公開の通知であれば[ヒューマンタスク]「告知文の作成」へ、既定の[その他]の経路は[終了イベント]「対象外」へ直接つなぎます。[ヒューマンタスク]「告知文の作成」の後は[終了イベント]「告知済み」です。
終了イベントは 2 つ置きます。終了イベントにつなげられるフローは 1 本だけなので、経路が分かれたまま終わる場合は、経路ごとに終了イベントを置きます。終了イベントに経路の名前を付けておけば、どの経路で終わったかがケースの図から読めます。
データ項目は次の 8 つです。右の列は、[ヒューマンタスク]「告知文の作成」での編集の可否です。[メッセージ開始イベント (Webhook)]には、データ項目ごとに編集の可否を設定する項目がありません。
| フィールド名 | データ項目名 | データタイプ | 告知文の作成 |
|---|---|---|---|
| q_webhook_body | 受信ボディ | 文字 (複数行) | 表示のみ |
| q_action | 通知の種類 | 文字 (単一行) | 表示のみ |
| q_repository | リポジトリ | 文字 (単一行) | 表示のみ |
| q_tag_name | タグ名 | 文字 (単一行) | 表示のみ |
| q_release_name | リリース名 | 文字 (単一行) | 表示のみ |
| q_release_url | リリースページ URL | 文字 (単一行) | 表示のみ |
| q_release_body | リリースノート | 文字 (複数行) | 表示のみ |
| q_announcement | 告知文 | 文字 (複数行) | 編集可 |
「受信ボディ」(q_webhook_body)は、受信したリクエストボディの書き込み先です。次の節で、工程のプロパティの[リクエストボディ保存先のデータ項目]に指定します。q_action から q_release_body までの 6 つを書き込むのは[スクリプトタスク]「通知の解析」です。「告知文」(q_announcement)は、[ヒューマンタスク]「告知文の作成」で処理担当者が入力する欄です。
[メッセージ開始イベント (Webhook)]の設定
工程のプロパティ画面で、次を設定します。
- API キー:半角英数のみ、最大 100 文字で設定します。[キーを自動生成]でも作れます
- 受信する HTTP リクエストのメソッド:POST
- 受信する HTTP リクエストの Content-Type:application/json
- リクエストボディ保存先のデータ項目:
q_webhook_body
リクエストボディの保存先に指定できるのは、文字 (複数行) または文字 (Markdown) のデータ項目です。
受信 URL は、この工程のプロパティ画面に表示されます。次の形式で、API キーは URL のパスに含まれます。GitHub 側に登録するのはこの URL です。
https://(ワークフロー基盤のドメイン)/System/Event/MessageStartHttp/(アプリ ID)/(工程番号)/(API キー)/start応答の内容
前の節と同じ[メッセージ開始イベント (Webhook)]のプロパティ画面で、GitHub へ返す本文を設定します。
- HTTP レスポンスの Content-Type:application/json;charset=UTF-8
- HTTP レスポンスの内容:下記
{
"caseId": "#{processInstanceId}"
}
GitHub はこの応答の中身を使いませんが、後述する配信の記録に残ります。ケース ID を返しておくと、どの配信がどのケースになったかを突き合わせられます。
アクセス元の IP アドレス制限
受信 URL は IP アドレス制限の対象です。Questetra BPM Suite は、初期状態では[メッセージ開始イベント (Webhook)]あての HTTP リクエストを外部からすべて拒否します。許可は[システム設定]>[IPアドレス制限]で登録します。この設定を行えるのはシステム管理権限を持つアカウントです。ワークフローアプリを作成できる権限とは別なので、権限がない場合はシステム管理者に依頼します。
登録するのは[メッセージ開始イベント/受信タスク設定]の 1 行です。
- [パスプレフィックス]— 選択肢[メッセージ開始イベント (Webhook) – 特定ノード]を選び、括弧で示された部分を受信 URL のアプリ ID と工程番号に置き換えます。許可するのはこの工程だけにし、全アプリや特定アプリの単位では許可しないでください
- [接続が許可されているネットワーク]— 次に説明する GitHub の送信元の範囲
GitHub は Webhook の送信元 IP アドレスの範囲を API で公開していて、https://api.github.com/meta の応答に含まれる hooks がそれにあたります。IPv4 と IPv6 の両方が並んでいますが、IP アドレス制限が対応しているのは IPv4 だけなので、IPv4 の範囲を登録します。
ただし、この範囲は変わることがあります。変わったあとも古い範囲のままにしておくと、通知が拒否されるようになります。範囲を確認して更新する運用を決めておいてください。
届く通知の種類
Webhook を登録した時点で、GitHub は ping という通知を 1 回送ります。 登録できたことを知らせるためのもので、リリースの通知ではありません。この 1 件でもケースが開始されます。
公開以外の通知も届きます。 リリースの通知には action という項目があり、published(公開)のほかに created、edited、deleted、prereleased、released、unpublished があります。GitHub の設定画面で選べるのはイベントの種類([Releases])までで、action の値までは絞り込めません。
1 回の公開で、通知は 1 件ではありません。 リリースを下書きにせず直接公開すると、created、published、released の 3 件が届き、ケースも 3 件開始されます。下書きを保存してから公開した場合は、下書き保存の時点で created が届き、公開の時点で published と released の 2 件が届きます。プレリリースとして公開した場合は released の代わりに prereleased が届き、released はプレリリースを正式なリリースに変更したときに届きます。
どの経路でも、公開の時点で published は 1 件だけ届きます。この記事で published を選り分けの条件にしているのはそのためです。
つまり、届いたリクエストの数だけケースが開始されます。 選り分けは Questetra BPM Suite 側で行います。この記事では、解析した action の値を[分岐 XOR ゲートウェイ]で見て、published 以外は[ヒューマンタスク]を通さずに[終了イベント]「対象外」へ流します。
対象外の通知でも、ケースそのものは 1 件ずつ残ります。ケース一覧で見分けられるように、「件名の設定」の節で件名を付けます。
受け取った JSON の解析
保存された JSON から値を取り出すには[スクリプトタスク]が必要です。SpEL 式には JSON を解析する機能がありません。
[スクリプトタスク]に次のスクリプトを設定します。q_webhook_body を読み、q_action から q_release_body までの 6 つのデータ項目に書き込みます。
function pick(obj, key) {
if (obj === undefined || obj === null) {
return '';
}
const value = obj[key];
if (value === undefined || value === null) {
return '';
}
return String(value);
}
const body = engine.findDataByVarName('q_webhook_body');
let json;
try {
json = JSON.parse(body);
} catch (e) {
json = {};
}
if (json === null || typeof json !== 'object') {
json = {};
}
let action = pick(json, 'action');
if (action === '' && pick(json, 'zen') !== '') {
action = 'ping';
}
engine.setDataByVarName('q_action', action);
engine.setDataByVarName('q_repository', pick(json.repository, 'full_name'));
engine.setDataByVarName('q_tag_name', pick(json.release, 'tag_name'));
engine.setDataByVarName('q_release_name', pick(json.release, 'name'));
engine.setDataByVarName('q_release_url', pick(json.release, 'html_url'));
engine.setDataByVarName('q_release_body', pick(json.release, 'body'));
キーがない場合に備えています。 ping の通知には action も release もありません。値の有無を確かめずに json.release.tag_name と書くと、release が無い時点でスクリプトの実行が止まります。止まるのはスクリプトの実行だけで、トークンはこの工程に留まらず、次の工程へ進みます。 エラーになった実行ではデータ項目への代入がひとつも反映されません。 途中まで書き込まれた状態にはならず、スクリプトが書き込む 6 つのデータ項目がすべて空のままのケースができます。「受信ボディ」(q_webhook_body)には、受信した内容がそのまま残ります。
スクリプトの先頭で定義している pick は、これを避けるための関数です。pick(json.release, 'tag_name') のように、オブジェクトとキーの名前を渡して使います。渡したオブジェクトが無い場合も、そのキーが無い場合も、空文字列を返すので、release が無い ping の通知でも実行は止まりません。
ping の通知には zen という項目があります。action が無く zen がある場合を ping とみなして、q_action に ping と入れています。
JSON.parse を try で囲んでいるのは、JSON として解釈できない内容が届いた場合に、スクリプトをエラーで終わらせないためです。この場合 q_action は空のままになり、公開の通知としては扱われません。空のリクエストボディや、オブジェクトではない JSON が届いた場合も同じです。
受信したリクエストボディは q_webhook_body にそのまま残ります。GitHub が送る内容の構造が変わって解析が合わなくなったときに、何が届いていたのかを後から確認できます。
件名の設定
[データ更新]「件名の設定」で、ケースの件名を設定します。設定対象に[件名]を選び、次の式を設定します。
#{#q_action == 'published' ? 'リリース公開' : '対象外'}(#{#q_action}) #{#q_repository} #{#q_tag_name}
published の通知であれば「リリース公開(published) yourname/your-repo v1.2.0」、ping の通知であれば「対象外(ping) yourname/your-repo」という件名になります。
処理しないケースは、件名でそれと分かるようにしておきます。 1 回の公開で複数のケースが開始されるので、件名が同じだと、どれが告知に進んだケースなのかをケース一覧から判断できません。
件名を付ける[データ更新]「件名の設定」は[分岐 XOR ゲートウェイ]「公開の通知かどうか」より前にあり、この時点では経路がまだ分かれていません。そのため、件名の式の中でも q_action を見て、公開の通知かどうかで書き分けます。式のうち条件で分かれるのは先頭だけで、あとはデータ項目をそのまま並べています。
yourname/your-repo の部分には、リポジトリの所有者とリポジトリ名が入ります。所有者は、個人アカウントに作ったリポジトリであればユーザ名、Organization に作ったリポジトリであれば Organization 名です。
公開の通知の選り分け
[分岐 XOR ゲートウェイ]「公開の通知かどうか」で、q_action の値を見ます。[ヒューマンタスク]「告知文の作成」へ向かう経路に、q_action が published と等しい、という条件を設定します。既定の[その他]の経路は[終了イベント]「対象外」へつなぎます。
これで、ping も、published 以外のリリースの通知も、告知の工程には進みません。
GitHub 側の設定
ここまでで、ワークフローアプリ側の設定は終わりです。GitHub に登録する前に、ワークフローアプリをリリースしておきます。登録した直後に GitHub が確認の通知(「届く通知の種類」で説明した ping)を送ってくるので、その時点で受信 URL が有効になっている必要があります。
通知を送るリポジトリの[Settings]から、[Webhooks]を開いて追加します。GitHub には[Settings]がいくつもあります。ここで開くのはリポジトリの[Settings]です。Organization の[Settings]にも[Webhooks]がありますが、そちらは Organization 全体に対する設定です。追加には、そのリポジトリの管理者権限が必要です。
登録する設定項目は次のとおりです。
- Payload URL — [メッセージ開始イベント (Webhook)]の受信 URL
- Content type — application/json
- Secret — 空のままにします(理由は後述)
- Which events would you like to trigger this webhook? — [Let me select individual events]を選び、[Releases]にチェックを入れます
- Active — チェックを入れます
[Secret]に文字列を登録すると、GitHub はリクエストの署名を X-Hub-Signature-256 という HTTP ヘッダに入れて送ります。受け取った側が、その署名で送信元を検証するためのものです。ただし[メッセージ開始イベント (Webhook)]が保存するのはリクエストボディだけで、HTTP ヘッダの値は参照できません。Secret を登録しても、署名の検証は行えません。
エンドポイントを守るのは、受信 URL に含まれる API キーと、「アクセス元の IP アドレス制限」で登録した許可範囲の 2 つです。
画面の構成は変わることがあります。画面が説明と違う場合は、GitHub の公式ドキュメントで最新の手順を確認してください。
届かないときの確認
GitHub 側には、送ったリクエストと受け取った応答の記録が残ります。リポジトリの[Settings]>[Webhooks]で対象の Webhook を開くと、[Recent Deliveries]に配信の一覧があります。リクエストのヘッダとボディ、応答のステータスコードとボディを、配信 1 件ごとに確認できます。同じ内容を送り直すこともできるので、Questetra BPM Suite 側の設定を直したあとの確認に使えます。表示されるのは直近 3 日分です。それより前の配信は確認も再送もできないので、設定を直したら早めに確かめてください。
応答のステータスコードごとの見方は、エラー対処編で説明しています。403 が返る場合は、IP アドレス制限に GitHub の範囲が登録されているかを確認してください。初期状態のままでは、GitHub からの通知はすべて 403 になります。
400 で本文に NodeDoesNotExist が返る場合は、受信 URL のどこかが違っています。API キーの誤りも、アプリ ID や工程番号の誤りも、アプリが未リリースの場合も、同じ応答が返ります。どこが違うのかは応答からは分かりません。攻撃する側に手がかりを与えないよう、原因を区別しない作りになっています。GitHub 側の[Recent Deliveries]に記録された送信先 URL と、プロパティ画面に表示される受信 URL を、1 文字ずつ突き合わせてください。
ケースは開始されているのに値が空の場合は、[スクリプトタスク]の解析が合っていません。q_webhook_body に保存された内容と、スクリプトが参照しているキーの名前を突き合わせてください。



