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",
  "direction": "outgoing",
  "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
direction	string	Message direction: "outgoing" (AI/human reply), "incoming" (customer message), or "echo" (sent from the connected phone). Only present when incoming forwarding is enabled.
externalUserId	string	Customer identifier (e.g., phone number). Present for "incoming" and "echo" messages.
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

AI Response (Outgoing)

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

Incoming Customer Message

When Forward incoming messages is enabled in the channel settings:

{
  "channelId": "550e8400-e29b-41d4-a716-446655440000",
  "channelIdentifier": "+5511999999999",
  "agentId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "sessionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "messageId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "response": "Hi, I'd like to check my order status",
  "timestamp": "2024-01-15T10:29:00.000Z",
  "direction": "incoming",
  "externalUserId": "+5511777777777"
}

Distinguishing Message Direction

Use the direction field to determine message type:

• "incoming" — a customer message forwarded to your server
• "echo" — a message sent from the connected phone directly (not via MAIA). Only available for non-official WhatsApp channels.
• "outgoing" or absent — an AI response or human operator reply (default behavior)

Echo Message (Sent from Connected Phone)

When Forward incoming messages is enabled and a message is sent from the connected phone (non-official WhatsApp channels only):

{
  "channelId": "550e8400-e29b-41d4-a716-446655440000",
  "channelIdentifier": "+5511999999999",
  "agentId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "sessionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "messageId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "response": "I'll check that for you right away",
  "timestamp": "2024-01-15T10:31:00.000Z",
  "direction": "echo",
  "externalUserId": "+5511777777777"
}

Echo Messages

Echo messages represent messages sent by the phone owner directly from their WhatsApp device — not through MAIA. These are only available for non-official WhatsApp channels, as the official WhatsApp Business API does not relay messages sent from the phone.

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