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:

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

Request Method: POST

Request Format

{
    "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

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

{
    "message": "Webhook received successfully"
}