Webhook Payload Reference

When an event triggers a webhook, MAIA sends an HTTP POST request with a JSON payload containing all relevant information about the message.

Payload Structure

{
  "channelId": "550e8400-e29b-41d4-a716-446655440000",
  "channelIdentifier": "+5511999999999",
  "agentId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "sessionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "messageId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "response": "Hello! How can I assist you today?",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "attachments": [
    {
      "id": "attachment-uuid",
      "url": "https://presigned-url.example.com/file.pdf",
      "type": "document",
      "size": 102400,
      "mimeType": "application/pdf"
    }
  ]
}

Field Reference

Field	Type	Description
channelId	string	Internal UUID of the channel
channelIdentifier	string	External identifier (e.g., WhatsApp phone number +5511999999999, username, etc.)
agentId	string	UUID of the AI agent that processed the message
sessionId	string	UUID of the conversation session
messageId	string	Unique UUID of this message
response	string	The message content/text
timestamp	string	ISO 8601 formatted timestamp
attachments	array	Optional array of file attachments

Attachments

When a message includes files, the attachments array contains objects with:

Field	Type	Description
id	string	Unique attachment identifier
url	string	Pre-signed URL to download the file (expires after a set period)
type	string	Attachment type: image, audio, video, or document
size	number	File size in bytes
mimeType	string	MIME type (e.g., application/pdf, image/png)

Pre-signed URLs

Attachment URLs are pre-signed and will expire. Download or process attachments promptly after receiving the webhook.

Example Payloads

Text-only Message

{
  "channelId": "550e8400-e29b-41d4-a716-446655440000",
  "channelIdentifier": "+5511999999999",
  "agentId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "sessionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "messageId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "response": "Your order #12345 has been shipped and will arrive in 2-3 business days.",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Message with Image Attachment

{
  "channelId": "550e8400-e29b-41d4-a716-446655440000",
  "channelIdentifier": "support-bot",
  "agentId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "sessionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "messageId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "response": "Here's the product image you requested:",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "attachments": [
    {
      "id": "img-001",
      "url": "https://storage.maiacompany.io/files/product.jpg?signature=xyz",
      "type": "image",
      "size": 245760,
      "mimeType": "image/jpeg"
    }
  ]
}

Message with Audio (Voice Note)

{
  "channelId": "550e8400-e29b-41d4-a716-446655440000",
  "channelIdentifier": "+5511888888888",
  "agentId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "sessionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "messageId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "response": "",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "attachments": [
    {
      "id": "audio-001",
      "url": "https://storage.maiacompany.io/files/voice.ogg?signature=abc",
      "type": "audio",
      "size": 51200,
      "mimeType": "audio/ogg"
    }
  ]
}

HTTP Headers

Each webhook request includes the following headers:

Header	Value
Content-Type	application/json
User-Agent	Maia-Webhook/1.0
X-Maia-Signature	HMAC-SHA256 signature (see Security)

Next Steps

• Security - Learn how to verify webhook signatures