# Webhook

Developers need to provide an API endpoint to receive and process incoming webhook requests. After the integration party creates a message, MaiAgent will send the AI assistant's response back to this Webhook endpoint.

**Webhook Flow:**

{% @mermaid/diagram content="sequenceDiagram
participant C as Developer
participant M as MaiAgent

```
C->>M: Call MaiAgent Create Message API
M->>C: Return Receipt (without message response)
Note right of M: AI Assistant
M->>C: Webhook calls developer-provided API to notify response result (JSON format)" fullWidth="false" %}
```

**Endpoint:** `https://<your-api-domain>/maiagent/webhook` (designed by developer)

**Request Method:** `POST`

### Request Format

```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"
}
```

### Request Parameters

| Parameter     | Type           | Required | Description                               |
| ------------- | -------------- | -------- | ----------------------------------------- |
| id            | string         | Yes      | Message unique identifier (UUID format)   |
| conversation  | string         | Yes      | Conversation identifier                   |
| sender        | object         | Yes      | Sender information                        |
| sender.id     | string         | Yes      | Sender ID                                 |
| sender.name   | string         | Yes      | Sender user ID                            |
| sender.avatar | string         | Yes      | Sender avatar URL                         |
| type          | string         | Yes      | Message type (e.g., outgoing)             |
| content       | string         | Yes      | Message content                           |
| feedback      | null \| object | No       | Feedback                                  |
| createdAt     | string         | Yes      | Message creation timestamp (milliseconds) |
| attachments   | array          | Yes      | Attachments list                          |
| citations     | array          | Yes      | Referenced files list                     |

### Citations Object Parameters

| Parameter | Type   | Required | Description                            |
| --------- | ------ | -------- | -------------------------------------- |
| id        | string | Yes      | File unique identifier                 |
| filename  | string | Yes      | File name                              |
| file      | string | Yes      | File URL                               |
| fileType  | string | Yes      | File type (e.g., jsonl)                |
| size      | number | Yes      | File size (bytes)                      |
| status    | string | Yes      | File status                            |
| document  | string | Yes      | Document identifier                    |
| createdAt | string | Yes      | File creation timestamp (milliseconds) |

### Request Example

```bash
curl -X POST \\
  -H "Content-Type: application/json" \\
  -d '{
    "id": "msg123",
    "conversation": "conv456",
    "sender": {
        "id": 789,
        "name": "Test User",
        "avatar": "<https://example.com/avatar.jpg>"
    },
    "type": "outgoing",
    "content": "This is a webhook test message",
    "feedback": null,
    "created_at": "1728219442000",
    "attachments": [],
    "citations": []
  }' \\
  https://<your-api-domain>/maiagent/webhook
```

### Response Format

### Successful Response

Please return 200 to let MaiAgent know the Webhook was successful, otherwise MaiAgent's Retry Webhook mechanism will be activated

```json
{
    "message": "Webhook received successfully"
}
```