ハウツーガイド - 動的Webhookトリガー

動的Webhookトリガーとは、プログラムによって設定および解除できるトリガーです。これは、コネクターを構築する対象アプリケーションのAPIで明示的に記載されている必要があります。次の例では、トリガーオブジェクト内のさまざまなブロックでWebhookの設定と解除のプロセスを定義できます。

WARNING

コネクターに静的webhookトリガーを定義する場合、動的webhookトリガーを定義できなくなる点に注意してください。 1つのコネクターで使用できるwebhookトリガーのタイプは1つだけです。コネクターには、ポーリングトリガーと1種類のwebhookトリガーの両方を含めることができます。

サンプルコネクター - Cisco Webex

ruby

{
  title: 'My Cisco Webex connector',

  # More connector code here
  triggers: {
    new_message: {
      title: 'New message',

      subtitle: "Triggers when a message event is " \
      "received from Cisco Webex",

      description: lambda do |input, picklist_label|
        "New <span class='provider'>message event</span> in " \
        "<span class='provider'>Cisco Webex</span>"
      end,

      help: "Triggers when webhook is sent from Cisco.",

      input_fields: lambda do |object_definitions|
        [
          {
            name: "id",
            label: "Room ID"
          }
        ]
      end,

      webhook_subscribe: lambda do |webhook_url, connection, input, recipe_id|
        post("https://api.ciscospark.com/v1/webhooks",
             name: "Workato recipe #{recipe_id}",
             targetUrl: webhook_url,
             resource: "messages",
             event: "created",
             filter: "roomId=#{input['id']}")
      end,

      webhook_notification: lambda do |input, payload, extended_input_schema, extended_output_schema, headers, params|
        payload["data"]
      end,

      webhook_unsubscribe: lambda do |webhook_subscribe_output, connection|
        delete("https://api.ciscospark.com/v1/webhooks/#{webhook_subscribe_output['id']}")
      end,

      dedup: lambda do |message|
        message["id"]
      end,

      output_fields: lambda do |object_definitions|
        [
          {
            name: "id"
          },
          {
            name: "roomId"
          },
          {
            name: "personId"
          },
          {
            name: "personEmail"
          },
          {
            name: "created"
          }
        ]
      end
    }
  },
  # More connector code here
}

ステップ1 - トリガーのタイトル、サブタイトル、説明、およびヘルプ

優れたトリガーを作成するための最初のステップは、トリガーの動作を適切に伝え、ユーザーに追加のヘルプを提供することです。そのため、Workatoではアクションのタイトルと説明を定義し、ヒントを提供できます。簡単に言えば、タイトルはアクションのタイトルであり、サブタイトルはアクションの詳細を示します。アクションの説明には、そのアクションが何を実現するかについての仕様と説明、および接続先アプリケーションのコンテキストが含まれます。最後に、ヘルプセグメントでは、アクションを機能させるために必要な追加情報をユーザーに提供します。

このステップの詳細については、SDKリファレンスを参照してください

ステップ2 - 入力フィールドの定義

このコンポーネントは、このトリガーを設定するユーザーに表示するフィールドをWorkatoに伝えます。この場合、ユーザーが候補者イベントのタイプを選択できるシンプルな入力フィールドが必要です。これは後でトリガーコード内で、トリガー固有のwebhookキーを作成するために使用されます。

ruby

    input_fields: lambda do |object_definitions|
      [
        {
          name: "id",
          label: "Room ID"
        }
      ]
    end,

上記で定義したもの以外にも、入力/出力フィールドにはさまざまなキーと値のペアが存在します。詳細については、入力フィールドを参照してください。

オブジェクト定義

object_definitionsが引数として渡されることに注意してください。 Workatoでは、コネクタービルダーがオブジェクトの定義を"object_definitions"キーで個別に指定できます。このキーは、オブジェクトの定義が大きい場合や動的に取得できる場合に使用します。

この詳細については、SDKリファレンスを参照してください

ステップ3 - トリガーのWebhookサブスクリプションロジック、Webhook処理、および解除ロジックの定義

レシピが開始されると、Webhookサブスクリプションが作成される必要があります。このWebhookサブスクリプションには、レシピに固有の"webhook url"を指定し、それを受信してジョブとして処理する必要があります。 webhook_subscribelambda関数はこの処理を担い、レシピが開始されるたびに実行されます。これを実現するために、lambda関数は次の引数を受け取ります:

webhook_url - 各レシピに固有の、動的に生成されたWebhook URL。
connection - Freshworksへのコネクションを作成する際にユーザーが指定した値に対応します
input - このトリガーの入力に対応します。この場合、単一の入力idです。
recipe_id - この特定のトリガーを使用するレシピIDに対応します。 Webhookサブスクリプションの追跡に役立ちます。

以下に、webhook_urlのサブスクリプションを処理するnew_messageトリガー内のlambda関数を示します。このブロック内で、Cisco Webex webhooks APIに記載されている関連詳細を使用して、Cisco spark APIエンドポイントにPOSTリクエストを送信します。

ruby

    webhook_subscribe: lambda do |webhook_url, connection, input, recipe_id|
      post("https://api.ciscospark.com/v1/webhooks",
           name: "Workato recipe #{recipe_id}",
           targetUrl: webhook_url,
           resource: "messages",
           event: "created",
           filter: "roomId=#{input['id']}")
    end,

TIP

webhook_subscribe内のHTTPリクエストでエラーが発生した場合、そのエラーはエンドユーザーに表示され、レシピの開始が阻止されます。

次のステップは、webhook_notificationslambda関数でWebhook処理を定義することです。トリガーに対するユーザー入力とwebhook自体の両方を表す多数の引数を使用できます。 webhookのペイロードをジョブとして送信するには、payload引数をそのまま渡すことができます。必要に応じて、headersから属性を追加することもできます。 Ciscoの場合、Cisco Webex webhooksガイドで説明されているペイロードから、関連しない詳細の一部を取り除いています。

ruby

    webhook_notification: lambda do |input, payload, extended_input_schema, extended_output_schema, headers, params|
      payload["data"]
    end,

Webhook検証

Workatoは、webhookのContent-Typeヘッダーで示されるJSONベースのwebhookに対して検証を実行し、ペイロードが有効なJSONであることを確認します。そうでない場合、Workatoは400 bad requestで応答します。
受信webhookペイロードはUTF-8互換であることが期待されており、UTF-8非互換の文字が見つかった場合、Workatoは400 bad requestで応答します。

最後の部分は、レシピが停止されたときにこのWebhookサブスクリプションを解除することです。これは、ターゲットアプリケーションでWebhookを適切にサニタイズするために不可欠です。これは、レシピが停止されたときに呼び出されるwebhook_unsubscribelambda関数によって処理されます。使用できる引数は1つで、webhook_subscribelambda関数の出力を表します。この場合、それはCiscoの/v1/webhooksエンドポイントへの最初のリクエストからのレスポンスでした。

この引数を使用して、作成されたサブスクリプションのidを識別し、対応するDELETEリクエストをv1/webhooksエンドポイントに送信してこのWebhookを削除できます。

ruby

    webhook_unsubscribe: lambda do |webhook_subscribe_output, connection|
      delete("https://api.ciscospark.com/v1/webhooks/#{webhook_subscribe_output['id']}")
    end,

上記のキーの詳細については、SDKリファレンスを参照してください

ステップ4 - 出力フィールドとdedupの定義

このセクションでは、トリガーの出力として表示するデータピルと、重複レコードによって重複ジョブが作成されるのを防ぐ方法について説明します。ジョブの繰り返しを防ぐには（Webhookが2回送信された場合など）、各レコードの一意の署名を作成する方法をコネクターに指示するdedupブロックを使用します。このシグネチャは各レシピに保存され、同じシグネチャを持つレコードが見つかった場合、ジョブは作成されません。

データピルには、output_fieldslambda関数を使用します。各データピルのname属性は、webhook_notificationslambda関数の出力であるHashのキーと一致する必要があります。

ruby

    dedup: lambda do |message|
      message["id"]
    end,

    output_fields: lambda do |object_definitions|
      [
        {
          name: "id"
        },
        {
          name: "roomId"
        },
        {
          name: "personId"
        },
        {
          name: "personEmail"
        },
        {
          name: "created"
        }
      ]
    end

ruby

  # Sample output of the webhook_notification: lambda function
  {
    "id": "Y2lzY29zcGFyazovL3VzL01FU1NBR0UvOTJkYjNiZTAtNDNiZC0xMWU2LThhZTktZGQ1YjNkZmM1NjVk",
    "roomId": "Y2lzY29zcGFyazovL3VzL1JPT00vYmJjZWIxYWQtNDNmMS0zYjU4LTkxNDctZjE0YmIwYzRkMTU0",
    "personId": "Y2lzY29zcGFyazovL3VzL1BFT1BMRS9mNWIzNjE4Ny1jOGRkLTQ3MjctOGIyZi1mOWM0NDdmMjkwNDY",
    "personEmail": "[email protected]",
    "created": "2015-10-18T14:26:16.000Z"
  }

出力フィールドブロックの詳細については、SDKリファレンスを参照してください

オブジェクト定義

この詳細については、SDKリファレンスを参照してください

ステップ5 - [任意] WorkatoがWebhookイベントに応答する方法の設定

Webhook送信者がカスタムレスポンスを必要とする場合は、そのための追加属性を設定できます。詳細はこちら

ステップ6 - Webhookイベントの保護

webhookを受信できるようになったので、受信webhookイベントの真正性を検証するための追加チェックの追加を検討できます。

レート制限

このトリガーには、webhookゲートウェイの制限が適用されます。

Last updated:

ハウツーガイド - 動的Webhookトリガー ​

サンプルコネクター - Cisco Webex ​

ステップ1 - トリガーのタイトル、サブタイトル、説明、およびヘルプ ​

ステップ2 - 入力フィールドの定義 ​

ステップ3 - トリガーのWebhookサブスクリプションロジック、Webhook処理、および解除ロジックの定義 ​

ステップ4 - 出力フィールドとdedupの定義 ​

ステップ5 - [任意] WorkatoがWebhookイベントに応答する方法の設定 ​

ステップ6 - Webhookイベントの保護 ​

レート制限 ​

ハウツーガイド - 動的Webhookトリガー

サンプルコネクター - Cisco Webex

ステップ1 - トリガーのタイトル、サブタイトル、説明、およびヘルプ

ステップ2 - 入力フィールドの定義

ステップ3 - トリガーのWebhookサブスクリプションロジック、Webhook処理、および解除ロジックの定義

ステップ4 - 出力フィールドとdedupの定義

ステップ5 - [任意] WorkatoがWebhookイベントに応答する方法の設定

ステップ6 - Webhookイベントの保護

レート制限