Guides

Webhookのリクエストの開発者向け情報

本チャプターについて

Webhookのリクエストの送信先のAPIを実装したり制御する開発者向けの情報を掲載します。


通信の検証

下記はリクエストに自動で付与されるHeaderです。

KEY内容
X-HMACHash Based Message Authentication Codeです。通信が正規のものかどうかを検証する際に利用できます。独自のAPIと連携をする場合は、この文字列を利用して通信の検証を行ってください。(https://narrow-attic-8d7.notion.site/webhook-4e57a895cb7d448980744f900eada27a)

X-HMACを利用することにより、Webhookの通信が正規のものかどうかを検証することができます。
Webhookの設定で指定したヘッダー情報も合わせて付与されます。

リクエストボディ

リクエストはJson形式のBodyが付与され、送信される。

※ GETメソッドを指定した場合は付与されません。

自動で送信されるパラメータ

パラメータ型値の例補足
webhookTypeString「user_utterance」 or 「agent_response」 or 「function_calling」user_utterance
stateObject(String:String){"username":"masashi"}miiboのステートという機能によって記録されたKey, Valueのmapです。https://zenn.dev/makunugi/books/f3d9eb62b6d133/viewer/a1c5e8
userIdStringユーザーを一意に識別する識別子
historyString直近の会話の履歴

下記は設定に応じて送信されるパラメータです。

  • Webhook設定のペイロードに設定したJSON
  • Functaion Callingで取得されたJSON

「自動で送信されるパラメータ」とマージされたJSONとしてリクエストに利用されます。

※マージされる際、キー名が同じ項目は、「設定に応じて送信されるパラメータ」に上書きされます。
※@{query} という記法を挿入することで、miiboが自動生成した検索クエリーを代入できます。

サンプルリクエスト

{
    "email": "hoge@miibo.jp",
    "functionName": "contact",
    "history": "user: 不具合を報告したいです。 \nai: もちろんです、正雄さん！不具合の内容を詳しく教えていただけますか？それによって、どのように対応するべきかが変わりますので。\nuser: miiboのログ画面でスクロールをすると固まります",
    "question": "miiboのログ画面でスクロールをすると固まる不具合が発生しています",
    "state": {
        "username": "正雄"
    },
    "userId": "xxxxxxxxxxxx",
    "utterance": "miiboのログ画面でスクロールをすると固まります",
    "webhookType": "function_calling"
}

※リトライ処理は行われません。リクエストに対するレスポンスのタイムアウト時間は3分ですが、AIの応答が遅くなることを防止するため、なるべく早いレスポンス速度であることが重要です。

Webhookのリクエストに対する応答でステートをアップデートする

Webhookのリクエストに対して、下記のようなレスポンスパラメータを含めることにより、ステートを更新できます。

{
  "state":{
        "recommended_item": "item1"
  }
}

Webhookのレスポンスで一次応答を返す

{
    "choices": [
        {
            "message": "天気予報をお伝えします。明日は晴れです。",
        }
    ],
    "forceFinish": false,
    "shouldFlush": true
}

上記のchoices、messageのオブジェクトに加え、shouldFlushにtrueを入れたオブジェクトをレスポンスの最上位に格納して返却します。
messageに格納された応答が一次回答として表示され、その後に後続のLLMの応答が返されます。Webhookのレスポンスが遅く、

また、forceFinishにtrueを入れたオブジェクトを返却すると、その時点で応答が強制終了されます。

Updated 2 months ago