Incoming Webhooks

Incoming webhooks let external systems push content into Monotree — chat messages, wall posts, or calendar entries. They use a token embedded in the URL, so no Authorization header is needed.

POST https://customer.monotree.com/api/open/v1/incoming/{token}

Actions

A single webhook is configured with one of these actions:

Action	Effect
`chat_message`	Sends a message to a chat room.
`direct_message`	Sends a message to a single user's private chat, as a bot.
`wall_post`	Creates a post on a wall.
`calendar_entry`	Adds an entry to the calendar.

direct_message is delivered to one user's private chat by a bot user and is configured with a target user id. It always requires a bot user as the sender. Its payload is the same simple text field (plus optional media). Create and manage these webhooks at scale via Manage Incoming Webhooks, or in the CMS Incoming Webhooks tab.

Payload

For chat_message and wall_post, the payload is a simple text field:

{
  "text": "Alert: Kitchen cooler temperature is 12°C"
}

For calendar_entry, send a structured object:

{
  "title": "Maintenance window",
  "starts_at": "2026-05-01",
  "starts_time": "08:00",
  "ends_at": "2026-05-01",
  "ends_time": "10:00"
}

Only title and starts_at are required for calendar_entry.

Attaching media

chat_message and wall_post can include images, videos, or documents via a media array of {url, type} pairs. Because webhooks have no bearer token, the two-step upload + media_ids flow used by the regular API does not apply — instead, Monotree fetches each URL and creates the Media records server-side.

{
  "text": "Image post from webhook",
  "media": [
    { "url": "https://example.com/photo.jpg", "type": "image" },
    { "url": "https://example.com/report.pdf", "type": "document" }
  ]
}

Rules

All items must be the same type (image / video / document). Mixed → 422.
Maximum 10 items per payload.
URLs must be publicly reachable from Monotree. Failed downloads → 422 with a descriptive error.
Per-URL download timeout: 15 seconds.

Examples

# chat_message / wall_post
curl -X POST https://customer.monotree.com/api/open/v1/incoming/YOUR_TOKEN \
  -H "Content-Type: application/json" \
  -d '{"text": "Alert: Kitchen cooler temperature is 12°C"}'

# wall_post with image
curl -X POST https://customer.monotree.com/api/open/v1/incoming/YOUR_TOKEN \
  -H "Content-Type: application/json" \
  -d '{"text": "See photo", "media": [{"url": "https://example.com/cooler.jpg", "type": "image"}]}'