> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/tech/maiagent-tech-ja/api-integration/webhook.md).

# Webhook

`開発者`は、受信した Webhook リクエストを受け取り処理するための API エンドポイントを用意する必要があります。MaiAgent は連携側でメッセージが作成された後、AI アシスタントの回答をこの Webhook エンドポイントへ返送します。

**Webhook のフロー：**

```mermaid
sequenceDiagram
    participant C as 開発者
    participant M as MaiAgent
    
    C->>M: 呼叫 MaiAgent 建立訊息 API
    M->>C: 回傳收到(不包含訊息回覆結果)
    Note right of M: AI助理
    M->>C: Webhook 呼叫開發者提供的 API 通知回覆結果(JSON 格式)
```

**エンドポイント：** `https://<your-api-domain>/maiagent/webhook` （開発者が自身で設計します）

**リクエストメソッド：** `POST`

### リクエスト形式

```json
{
    "id": "string",
    "conversation": "string",
    "sender": {
        "id": "number",
        "name": "string",
        "avatar": "string"
    },
    "type": "string",
    "content": "string",
    "feedback": "null | object",
    "created_at": "string",
    "attachments": "array",
    "citations": "array"
}
```

### リクエストパラメータの説明

| パラメータ                              | 型      | 必須     | 説明                    |
| ---------------------------------- | ------ | ------ | --------------------- |
| id                                 | string | はい     | メッセージの一意な識別子（UUID 形式） |
| conversation                       | string | はい     | 会話の識別子                |
| sender                             | object | はい     | 送信者の情報                |
| [sender.id](http://sender.id/)     | string | はい     | 送信者 ID                |
| [sender.name](http://sender.name/) | string | はい     | 送信者のユーザー ID           |
| sender.avatar                      | string | はい     | 送信者のアバター URL          |
| type                               | string | はい     | メッセージの種類（例：outgoing）  |
| content                            | string | はい     | メッセージの内容              |
| feedback                           | null   | object | いいえ                   |
| createdAt                          | string | はい     | メッセージ作成のタイムスタンプ（ミリ秒）  |
| attachments                        | array  | はい     | 添付ファイルの一覧             |
| citations                          | array  | はい     | 引用ファイルの一覧             |

### Citations オブジェクトのパラメータ

| パラメータ     | 型      | 必須 | 説明                  |
| --------- | ------ | -- | ------------------- |
| id        | string | はい | ファイルの一意な識別子         |
| filename  | string | はい | ファイル名               |
| file      | string | はい | ファイル URL            |
| fileType  | string | はい | ファイルの種類（例：jsonl）    |
| size      | number | はい | ファイルサイズ（バイト）        |
| status    | string | はい | ファイルの状態             |
| document  | string | はい | ドキュメントの識別子          |
| createdAt | string | はい | ファイル作成のタイムスタンプ（ミリ秒） |

### リクエスト例

```bash
curl -X POST \\
  -H "Content-Type: application/json" \\
  -d '{
    "id": "msg123",
    "conversation": "conv456",
    "sender": {
        "id": 789,
        "name": "テストユーザー",
        "avatar": "<https://example.com/avatar.jpg>"
    },
    "type": "outgoing",
    "content": "これは webhook のテストメッセージです",
    "feedback": null,
    "created_at": "1728219442000",
    "attachments": [],
    "citations": []
  }' \\
  https://<your-api-domain>/maiagent/webhook
```

### レスポンス形式

### 成功レスポンス

Webhook が正常に受信されたことを MaiAgent に伝えるため、200 を返してください。返さない場合、MaiAgent の Webhook 再試行（Retry）の仕組みが起動します。

```json
{
    "message": "Webhook 接收成功"
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.maiagent.ai/tech/maiagent-tech-ja/api-integration/webhook.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.