Webhooks

Webhooksは、事前定義されたイベントの発生時に2つのアプリケーション間で開始される自動トリガーです。この場合、Business Logicを外部サーバーに配置することを選択した場合、開発プラットフォームとしてWebhooksを選択できます。外部サーバーがREST APIを通じてConvoKraftから公開アクセス可能であることを確認する必要があります。Business Logicを実行するために、Action実行中の対応する呼び出しポイントで設定されたWebhook URLがConvoKraftによって呼び出されます。

WebhookサーバーはConvoKraft Botの適切な機能のために、以下のリクエストおよびレスポンス形式に準拠する必要があります。

リクエスト形式

ConvoKraftは、設定されたWebhook URLに以下の形式でリクエストを送信します。

{
"todo": "prompt || execute || fallback || button",
"bot" : "",
"action" : "",
"button_id" : "",
"environment" : "development || production"
"params":{
},
"userInput" : "",
"previousParam" : "",
"user" : {},
"org" : {},
"broadcast" : {},
"cache" : {},
"sessionData" : {}
"clientData" : {} 
}

レスポンス形式

ConvoKraftは、意図した応答を理解してユーザーに伝えるために、Webhook URLからのレスポンスが以下の形式であることを期待します。ConvoKraftは、コンテンツをさまざまな形式で表示するための複数の応答タイプをサポートしています。応答を設定する際は、定義された標準に従う必要があります。応答構造の詳細については、こちらのセクションを参照してください。

ケース1：入力paramをユーザーにプロンプトする必要がある場合

{
"status" : "prompt",
    "prompt" : {
        "param_name" : "leave_type",
        "options":[  
                    { "id" : "111" ,"label" : "", "image" : "image_url"},
                    {"id" : "112" ,"label" :"" ,"image" : "image_url"}
        ],
"buttons" : []
    },
    "message" : "You don't have enough casual leaves. Please choose some other leave type.",
    "data" : {}  
}

ケース2：出力メッセージをユーザーに表示する必要がある場合

{
    "status" : "execution",
    "message":"Please check your screen.",
    "card":[],
    "data":{},
    "broadcast":{},
    "trigger":{},
    "followup" : {}    
}

Webhook URLから受信するレスポンスには、以下のようないくつかの制限があります：

• レスポンスの最大サイズは100 KBです。
• リクエストタイムアウトの最大時間は5秒です。

レスポンスが上記のガイドラインに準拠していない場合、ユーザーへの応答としてエラーメッセージが送信されます。

Webhook呼び出しのセキュリティ保護

Webhookリクエストは、信頼できないリクエストの処理を回避するために、Webhookサーバーがリクエストの発信元がConvoKraftであることを検証できるようにセキュリティ保護できます。ConvoKraftはDigital Signature Algorithm(DSA)暗号システムを使用してセキュリティキーを生成します。これは、Webhookサーバーがリクエストを検証するために使用する必要があります。

1. 開発プラットフォームの選択時にWebhook呼び出しのセキュリティ保護を選択すると、ConvoKraftはDSA暗号システムに基づいて秘密鍵と公開鍵を自動生成します。これらの両方のキーは暗号化されてConvoKraftのサーバーに保存され、公開鍵のみがCatalystコンソールで開発者に公開されます。

2. Webhookサーバーにリクエストを送信する際、ConvoKraftは保存された秘密鍵を使用してデジタル署名を生成し、リクエストヘッダーX-CONVOKRAFT-SIGNATUREに署名を送信します。ユーザーがチャットウィンドウにメッセージを入力すると、メッセージは秘密鍵で暗号化され、ヘッダーのデジタル署名とともにWebhookサーバーにリクエストボディとして送信されます。

3. Webhookサーバーがこのメッセージを受信すると、リクエスト内の受信したデジタル署名と暗号化された公開鍵を使用して作成されたオリジナルの署名を比較します。不一致が見つかった場合、メッセージが改ざんされたことを意味します。

実装

Botを作成した後、開発プラットフォームとしてWebhooksを選択し、以下の手順に従います：

1. Business Logicコードが存在する外部サーバーのWebhook URLを入力します。Botの設定済みActionsの実行時に、このURLがアクセスされます。

   

2. 会話中のすべてのユーザーメッセージの後にWebhook URLを呼び出すか、会話の特定のコンテキストが終了するたびに呼び出すかを選択できます。

   

3. Botの作成が完了すると、ConvoKraft Botの重要な情報を一覧表示するBotの詳細ページが表示されます。

   生成された公開鍵を表示するには、Botの詳細ページのShow keyボタンをクリックします。

   

   Show keyオプションをクリックすると、Security Keyポップアップに公開鍵が表示されます。

   

   この公開鍵は開発環境ですぐに使用されます。Catalystプロジェクトをデプロイすると、本番環境で使用されます。