Webhook

Conversation platform Webhooks: push visitor messages and AI or human replies to your system in real time, with support for the MaiAgent standard format, Genesys Cloud, and custom Jinja2 templates

Webhooks are configured on a conversation platform (Inbox). Whenever a new message is created in a conversation on that platform, MaiAgent pushes the message to your specified endpoint via an HTTP request. A conversation platform can have multiple Webhooks, each with its own message direction and format.

Configuration path: Customer Support Conversations → Conversation Platforms → Edit platform → Webhook Settings → Add Webhook. For API platforms, Webhook Settings is in the “Integrations and Login” group on the left. For messaging platforms such as LINE, it is in the tab bar at the top. Web and internal platforms do not have this tab. For admin interface instructions, see Webhook in the user manual.

When you send a message through the Create conversations and messages API, the response only confirms that the message was created. The Agent's reply is generated asynchronously and pushed to you through an Outgoing Webhook. This is the standard way to receive replies in an API integration.

How it works

When a human support agent replies in the admin interface, the reply is also an Outgoing message and is pushed to the Outgoing Webhook. The payload's sender.type distinguishes AI from human senders.

Webhook types

Type	Trigger	Typical use
Outgoing	A reply from an Agent or human support agent is created	Receive AI replies and forward them to your own frontend or messaging app
Incoming	A visitor message is created (across all channels, including API, Web Chat, and LINE)	Synchronize conversation records to a support system or data warehouse, or use them for auditing
Receive	An external platform calls MaiAgent	Receive messages sent back by an external support platform (currently supports Genesys Cloud Open Messaging)

This page covers Outgoing and Incoming.

Configuration fields

Field	Description
Name	Custom identifying name
Type	Outgoing／Incoming／Receive
Webhook URL	URL that receives the pushed messages
HTTP Method	POST (default)／PUT／PATCH
Headers	Custom headers added to every request (such as your system's API key)
Payload Format	MaiAgent Standard Format／Genesys Cloud／Custom Template (Jinja2)
Enabled	When disabled, no messages are pushed; the configuration is retained
secretToken (API field)	When set, every request includes an X-Webhook-Secret: <token> header. The admin form only displays Secret Token for the Receive type. To include an authentication value for Outgoing／Incoming, configure it through the API, or add a custom header under Headers

Pushed requests are not signed. X-Webhook-Secret and custom headers are fixed strings sent as configured, rather than an HMAC computed over the request content. Use HTTPS endpoints only, and compare this value on the receiving side.

MaiAgent standard format

Content-Type: application/json, with the following content (Outgoing and Incoming share the same structure; type indicates the direction):

{
  "id": "2491074a-6d23-4289-af45-caa12531420e",
  "type": "outgoing",
  "content": "Hello, how can I help you?",
  "created_at": "2026-09-09T10:15:30.123456+00:00",
  "conversation": {
    "id": "8e44604a-8278-4c96-96b5-3e5a0548d738",
    "title": "Question about the return process",
    "type": "individual",
    "status": "open",
    "progress_status": "ai_processing",
    "auto_reply_enabled": true,
    "assignee": null
  },
  "inbox": {
    "id": "1f9c1c1e-4d1a-4b1e-9d0e-7b2f4a5c6d7e",
    "name": "Website Support",
    "channel_type": "web"
  },
  "contact": {
    "id": "c0ffee00-1111-2222-3333-444455556666",
    "name": "Wang Xiaoming",
    "email": null,
    "phone_number": null
  },
  "sender": {
    "id": "5c1d3e2a-0000-4b1e-9d0e-7b2f4a5c6d7e",
    "name": "AI Support Agent",
    "type": "chatbot"
  },
  "attachments": [
    {
      "id": "a1b2c3d4-0000-4b1e-9d0e-7b2f4a5c6d7e",
      "type": "image",
      "filename": "photo.jpg",
      "source_url": "https://example.com/photo.jpg"
    }
  ],
  "metadata": {}
}

Field descriptions

Field	Type	Description
id	string	Message ID (UUID)
type	string	incoming (visitor message)／outgoing (AI or human reply)
content	string	Message text
created_at	string	ISO 8601 timestamp
conversation.id	string	Conversation ID
conversation.title	string	Conversation title
conversation.type	string	individual／group
conversation.status	string	open／queued (waiting for a human agent)／resolved
conversation.progress_status	string	Current handling state: ai_processing／waiting_for_human／human_serving／resolved／open
conversation.auto_reply_enabled	boolean	false means AI has stopped replying automatically (handoff to a human in progress)
conversation.assignee	object | null	Support member taking over { id, name }; null if unassigned
inbox.id / inbox.name	string	Conversation platform ID and name
inbox.channel_type	string	web／line／messenger／instagram／telegram／teams／email／whatsapp／slack／team_plus／line_works／viber
contact	object | null	Visitor (contact) { id, name, email, phone_number }
sender.type	string	chatbot (Agent)／user (human support agent)／contact (visitor)
attachments[]	array	Attachments { id, type, filename, source_url }; type is image／video／audio／sticker／other
metadata	object	Additional message data

attachments[].source_url is the attachment's source URL (the original link provided by an external platform). This field may be empty for files stored by MaiAgent, such as files uploaded via the API or generated by AI. If you need a downloadable URL, use a custom template to access attachment.file.url (see the example below), or call the message API with the message ID to retrieve attachments.

Custom templates (Jinja2)

If your system requires a specific JSON structure, select Custom Template and write the payload using Jinja2 syntax. The rendered template must be valid JSON; it is validated once with test data when saved.

Available variables

Variable	Content
message	id, type, content, created_at (datetime), metadata
conversation	id, title, type, status, progress_status, auto_reply_enabled, assignee (may be None; when present, use assignee.id, assignee.user.name)
inbox	id, name, channel_type
contact	id, name, email, phone_number, source_id (the sourceId you provide through the identity synchronization API); may be None
sender	id, name; sender_type is chatbot／user／contact
attachments	Attachment list; each entry has id, type, filename, source_url, file (file.url is a downloadable URL)
now	Time at rendering (datetime)

Always output strings through the | tojson filter to correctly escape quotes and newlines.

Example: return your system's user ID and downloadable attachment URLs

{
  "external_user_id": {{ (contact.source_id if contact else "") | tojson }},
  "conversation_id": "{{ conversation.id }}",
  "direction": "{{ message.type }}",
  "from_human_agent": {{ (sender_type == "user") | tojson }},
  "text": {{ message.content | tojson }},
  "attachments": [{% for a in attachments %}{
    "type": "{{ a.type }}",
    "url": {{ (a.file.url if a.file else a.source_url) | tojson }}
  }{% if not loop.last %},{% endif %}{% endfor %}],
  "sent_at": "{{ message.created_at.isoformat() }}"
}

Delivery behavior

• Each message is pushed once to each enabled Webhook. The request timeout is 30 seconds.

• A 2xx response indicates success. Non-2xx responses or timeouts are recorded as failures, with no automatic retries. If your system requires reliable delivery, persist the data in your endpoint before responding with 2xx, and deduplicate using the message id.

• Endpoint URLs are subject to SSRF protection: destinations in private network ranges or at internal addresses are rejected.

• View the request content, response, and status code for each push in the Webhook tab on the Agent page for troubleshooting.

Manage Webhooks through the API

Besides the admin interface, you can create and maintain Webhooks through the API (fields correspond to the admin settings). See Quickstart for authentication.

# List / Create
GET  https://api.maiagent.ai/api/v1/inboxes/{inboxId}/webhooks/
POST https://api.maiagent.ai/api/v1/inboxes/{inboxId}/webhooks/

# Update / Delete
PATCH  https://api.maiagent.ai/api/v1/inboxes/{inboxId}/webhooks/{webhookId}/
DELETE https://api.maiagent.ai/api/v1/inboxes/{inboxId}/webhooks/{webhookId}/

{
  "name": "Synchronize replies to the support system",
  "direction": "outgoing",
  "isEnabled": true,
  "url": "https://your-system.example.com/maiagent/reply",
  "method": "POST",
  "headers": { "X-Api-Key": "your-key" },
  "templatePreset": "maiagent_standard",
  "customTemplate": null,
  "secretToken": "shared-secret"
}

Get inboxId from inbox.id in the Create conversation response, or view it on the conversation platform settings page in the admin interface.

Differences from handoff Webhooks

The Webhooks on this page push events at the message level. If your system needs to know when a conversation is handed off to a human and when it returns to AI (for example, when your support system takes over), use the separate set of handoff Webhooks that operate at the conversation lifecycle level. See Third-party support system integration (including handoff).