Webhook

Required DeveloperProvide an API endpoint to receive and handle incoming webhook requests. After MaiAgent creates a message on the integrator side, it will send the AI assistant's reply back to this Webhook endpoint.

Webhook flow:

Endpoint: https://<your-api-domain>/maiagent/webhook (Designed by the 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 parameter description

Parameter	Type	Required	Description
id	string	Yes	Unique message 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
createdAt	string	Yes	Message creation timestamp (milliseconds)
attachments	array	Yes	List of attachments
citations	array	Yes	List of citation files

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

Return 200 to let MaiAgent know the Webhook succeeded, otherwise MaiAgent will trigger a Retry Webhook mechanism

{
    "message": "Webhook received successfully"
}