ハウツーガイド - 静的webhookトリガー
静的webhookトリガーとは、手動登録が必要なトリガーです。 通常、ユーザーが提供されたwebhook URLを使用して、アプリケーションのUIでwebhookサブスクリプションを作成します。
WARNING
コネクターに静的webhookトリガーを定義する場合、動的webhookトリガーを定義できなくなる点に注意してください。 1つのコネクターで使用できるwebhookトリガーのタイプは1つだけです。 コネクターには、ポーリングトリガーと1種類のwebhookトリガーの両方を含めることができます。
サンプルコネクター - Greenhouse
{
title: 'My Greenhouse connector',
# More connector code here
webhook_keys: lambda do |params, headers, payload|
"#{params['org_id']}@#{payload['action']}"
end,
triggers: {
new_event: {
title: 'New Candidate Event',
subtitle: "Triggers when a Candidate event is received " \
"from Greenhouse",
description: lambda do |input, picklist_label|
"New <span class='provider'>candidate event</span> " \
"in <span class='provider'>Greenhouse</span>"
end,
help: lambda do |input, picklist_label, connection, webhook_base_url|
next unless webhook_base_url.present?
<<~HTML
Creates an job when an event is received from Greenhouse. To set this webhook up,
you will need to register the webhook below in Greenhouse under "settings" => "webhooks" => "new". <br>
<b>Webhook endpoint URL</b>
<b class="tips__highlight">#{webhook_base_url}?org_id=#{connection['org_id']}</b>
HTML
end,
input_fields: lambda do |object_definitions|
[
{
name: 'event_type',
label: 'Event',
control_type: 'select',
pick_list: 'events',
optional: false,
hint: 'Select specific event.'
}
]
end,
webhook_key: lambda do |connection, input|
"#{connection['org_id']}@#{input['event_type']}"
end,
webhook_notification: lambda do |input, payload, extended_input_schema, extended_output_schema, headers, params|
payload.dig('payload', 'candidate')
end,
dedup: lambda do |record|
record['id']
end,
output_fields: lambda do |object_definitions|
[
{
name: 'id'
},
{
name: 'rejected_at'
},
{
name: 'prospect'
},
{
name: 'prospect_detail',
type: 'object',
properties: [
{
name: 'prospect_pool',
type: 'object',
properties: [
{
name: 'id',
type: 'integer',
control_type: 'integer'
},
{
name: 'name'
}
]
},
]
}
]
end,
sample_output: lambda do |connection, input|
if input['event_type'] == "candidate_stage_change"
get("v1/applications?per_page=1")&.dig(0) || {}
else
get("v1/#{input['object']&.pluralize}?per_page=1")&.dig(0) || {}
end
end
}
},
pick_lists: {
events: lambda do |connection|
[
["Candidate Updated", "update_candidate"],
["Candidate Stage Changed", "candidate_stage_change"]
]
end
}
# More connector code here
}手順：
ステップ1 - webhook_keys属性を設定し、コネクターの静的webhook URLを取得する
webhook_keysはトップレベルのキー（コネクター全体の定義）です。 このlambda関数は、割り当てられたwebhook URLを介してコネクターが受信する各webhookに対して呼び出され、受信webhookごとにルーティングキーを定義できます。 例:
- この定義の場合
webhook_keys: lambda do |params, headers, payload|
"#{params['org_id']}@#{payload['action']}"
end,- および、Greenhouseからの次の短縮された本文を持つ受信webhookの場合
URL: https://www.workato.com/user/123/connector/abc?org_id=555
{
"action": "candidate_stage_change",
"payload": {
"application": {
"id": 265277,
"rejected_at": null,
"prospect": false,
"status": "active",
"applied_at": "2013-03-22T00:00:00Z",
"last_activity_at": "2015-02-09T16:38:36Z",
"url": "https://app.greenhouse.io/people/265772?application_id=265277",
"source": {
"id": 31,
"name": "Agency"
},
# More information here
}このwebhookペイロードに対する結果のwebhook_keys出力は、555@candidate_stage_changeになる必要があります。 このキーは、複数の静的webhookトリガーがある場合に、これらのイベントを適切なトリガーにルーティングするために使用されます。
コネクターの静的Webhook URLを取得するには、Connector SDK＞ソースコードの下にあるテストコードタブに移動します。 静的webhook URLは、Static webhook URIというラベルの展開可能なセクションにあります。
テストコード環境の静的Webhook URL
ステップ2 - トリガーのタイトル、サブタイトル、説明
優れたトリガーを作成するための最初のステップは、トリガーの動作を適切に伝え、ユーザーに追加のヘルプを提供することです。 そのため、Workatoではアクションのタイトルと説明を定義し、ヒントを提供できます。 簡単に言えば、タイトルはアクションのタイトルであり、サブタイトルはアクションの詳細を示します。 アクションの説明には、そのアクションが何を実現するかについての仕様と説明、および接続先アプリケーションのコンテキストが含まれます。
このステップの詳細については、SDKリファレンスを参照してください
ステップ3 - 静的webhook URLを使用してヘルプを定義する
静的webhookトリガーを構築するうえで重要なもう1つの部分は、ユーザーがそれを取得して登録できるように、webhook URLを目立つように表示することです。 これを行うには、コネクターの静的webhook URLを表示できるhelp lambdaを利用できます。 さらに、表示されるwebhook URLにクエリパラメーターを追加できます。これは、webhook_keyおよびwebhook_keysと組み合わせて使用し、イベントを特定のレシピにルーティングできます。
help: lambda do |input, picklist_label, connection, webhook_base_url|
next unless webhook_base_url.present?
<<~HTML
Creates an job when an event is received from Greenhouse. To set this webhook up,
you will need to register the webhook below in Greenhouse under "settings" => "webhooks" => "new". <br>
<b>Webhook endpoint URL</b>
<b class="tips__highlight">#{webhook_base_url}?org_id=#{connection['org_id']}</b>
HTML
end,この例では、org_idというコネクションから取得した入力を使用しています。これは、このレシピで使用されるコネクションの特定のGreenhouse組織を表します。 これは、複数のコネクションがある場合に、このwebhookを正しいレシピにルーティングするために重要になります。
helpの詳細については、SDKリファレンスを参照してください。
ステップ4 - 入力フィールドを定義する
このコンポーネントは、このトリガーを設定するユーザーに表示するフィールドをWorkatoに伝えます。 この場合、ユーザーが候補者イベントのタイプを選択できるシンプルな入力フィールドが必要です。 これは後でトリガーコード内で、トリガー固有のwebhookキーを作成するために使用されます。
input_fields: lambda do |object_definitions|
[
{
name: 'event_type',
label: 'Event',
control_type: 'select',
pick_list: 'events',
optional: false,
hint: 'Select specific event.'
}
]
end,
新規イベント入力フィールド
上記で定義したもの以外にも、入力/出力フィールドにはさまざまなキーと値のペアが存在します。 詳細については、入力フィールドを参照してください。
オブジェクト定義
object_definitionsが引数として渡されることに注意してください。 Workatoでは、コネクタービルダーがオブジェクトの定義を"object_definitions"キーで個別に指定できます。 このキーは、オブジェクトの定義が大きい場合や動的に取得できる場合に使用します。
この詳細については、SDKリファレンスを参照してください
ステップ5 - トリガーwebhookキーを定義する
エンドユーザーからの入力を定義した後、コネクターのwebhook_key lambda関数の定義に進むことができます。 このlambda関数は、ユーザーのコネクション値と、このトリガーのinput_fieldsからの入力の2つの引数を受け取ります。 これにより、webhookトリガーに固有のキーとなる文字列を作成できます。
ステップ1のこのwebhook_keyとwebhook_keysにより、2つの一意の文字列が生成されます。 受信webhookがコネクターのwebhook URLに届くと、webhook_keys lambda関数からの結果の出力文字列が、各トリガー内のwebhook_key lambda関数から生成された文字列と照合されます。 一致する場合、webhookはこのトリガー（一致する他のすべてのトリガーも含む）にルーティングされます。
webhook_key: lambda do |connection, input|
"#{connection['org_id']}@#{input['event_type']}"
end,ステップ1のwebhookの例では、webhook_keysの出力文字列が555@candidate_stage_changeになることがわかります。 connection['org_id']とinput['event_type']を利用するwebhook_keyの出力が一致すると、イベントはこのトリガーにルーティングされます。
ステップ6 - webhookの処理方法を定義する
webhook_notification lambda関数は、ルーティングされたすべてのwebhookに対してコネクターが実行すべき処理を記述します。 トリガーに対するユーザー入力とwebhook自体の両方を表す多数の引数を使用できます。 webhookのペイロードをジョブとして送信するには、payload引数をそのまま渡すことができます。 必要に応じて、headersから属性を追加することもできます。 Greenhouseの場合、Greenhouse webhooks documentationに記載されているペイロードから、関連性の低い詳細を一部取り除いています。
webhook_notification: lambda do |input, payload, extended_input_schema, extended_output_schema, headers, params|
payload.dig('payload', 'application')
end,Webhook検証
- Workatoは、webhookの
Content-Typeヘッダーで示されるJSONベースのwebhookに対して検証を実行し、ペイロードが有効なJSONであることを確認します。 そうでない場合、Workatoは400 bad requestで応答します。 - 受信webhookペイロードはUTF-8互換であることが期待されており、UTF-8非互換の文字が見つかった場合、Workatoは400 bad requestで応答します。
webhook_keyおよびwebhook_notificationキーの詳細については、SDKリファレンスを参照してください
ステップ7 - 出力フィールドとdedupを定義する
このセクションでは、トリガーの出力として表示するデータピルと、重複レコードによって重複ジョブが作成されるのを防ぐ方法について説明します。 ジョブが繰り返されるのを防ぐには（これはwebhookが2回送信された場合に発生する可能性があります）、各レコードの一意のシグネチャを作成する方法をコネクターに伝えるdedupキーを使用します。 このシグネチャは各レシピに保存され、同じシグネチャを持つレコードが見つかった場合、ジョブは作成されません。
データピルには、output_fieldsキーを使用します。 各データピルのname属性は、単一のwebhookペイロードのキーと一致する必要があります。
dedup: lambda do |record|
record['id']
end,
output_fields: lambda do |object_definitions|
[
{
name: 'id'
},
{
name: 'rejected_at'
},
{
name: 'prospect'
},
{
name: 'prospect_detail',
type: 'object',
properties: [
{
name: 'prospect_pool',
type: 'object',
properties: [
{
name: 'id',
type: 'integer',
control_type: 'integer'
},
{
name: 'name'
}
]
},
]
}
]
end,
新規イベント出力フィールド
# Sample output of the webhook_notification: lambda function
{
"id": "a1241",
"rejected_at": "2020-01-12 10:57:03",
"prospect": true,
"prospect_detail": {
"id": 12491,
"name": "John Doe"
}
}output fieldsキーの詳細については、SDKリファレンスを参照してください
オブジェクト定義
object_definitionsが引数として渡されることに注意してください。 Workatoでは、コネクタービルダーがオブジェクトの定義を"object_definitions"キーで個別に指定できます。 このキーは、オブジェクトの定義が大きい場合や動的に取得できる場合に使用します。
この詳細については、SDKリファレンスを参照してください
ステップ8 - サンプル出力を定義する
トリガーの任意の補助コンポーネントであるsample outputキーは、それでも、データピルの値がどのようなものかのコンテキストをユーザーに提供することで、ユーザーエクスペリエンスを大幅に向上させます。 これにより、ユーザーはレシピをより迅速に作成できます。
sample_output: lambda do |connection, input|
if input['event_type'] == "candidate_stage_change"
get("v1/applications?per_page=1")&.dig(0) || {}
else
get("v1/#{input['object']&.pluralize}?per_page=1")&.dig(0) || {}
end
endsample outputキーの詳細については、SDKリファレンスを参照してください
ステップ9 - webhookイベントを保護する
webhookを受信できるようになったので、受信webhookイベントの真正性を検証するための追加チェックの追加を検討できます。
レート制限
このトリガーには、webhookゲートウェイの制限が適用されます。
Last updated: