Manage Incoming Webhooks

Provision and manage incoming webhooks over the API instead of the Open API → Incoming Webhooks tab in the CMS. You can create a direct_message webhook for a specific user — resolve them via the Users endpoints first — when you need a standing URL to post to. If you just want to send direct messages from your backend, use the Direct Messages endpoint rather than provisioning a webhook per user.

Required scope: read:incoming_webhooks, write:incoming_webhooks.

Endpoints

GET

/api/open/v1/incoming-webhooks

List your incoming webhooks

GET

/api/open/v1/incoming-webhooks/{id}

Get a single incoming webhook

POST

/api/open/v1/incoming-webhooks

Create an incoming webhook

PUT

/api/open/v1/incoming-webhooks/{id}

Update an incoming webhook

POST

/api/open/v1/incoming-webhooks/{id}/revoke

Revoke an incoming webhook (permanent)

Create

curl -X POST https://customer.monotree.com/api/open/v1/incoming-webhooks \
  -H "Authorization: Bearer mono_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Reply reminder for Alex",
    "action": "direct_message",
    "config": { "user_id": 4012 },
    "bot_user_id": 873
  }'

Request body

Field	Type	Notes
`name`	string	Required. A label for the webhook.
`action`	string	Required. One of `chat_message`, `direct_message`, `wall_post`, `calendar_entry`.
`config`	object	Required. The action's target — `{ "user_id": ... }` for `direct_message`, `{ "room_id": ... }` for `chat_message`, `{ "wall_id": ... }` for `wall_post`.
`bot_user_id`	integer	Optional. The bot user that sends the content. If omitted, a bot is created automatically. `direct_message` always requires a bot.
`use_bot_user`	boolean	Optional, default `true`. Set `false` to attribute content to the token owner instead of a bot — not allowed for `direct_message`.

Response

The trigger URL and token are returned once on create and cannot be retrieved again — store them when you receive them.

{
  "data": {
    "id": 47,
    "name": "Reply reminder for Alex",
    "action": "direct_message",
    "config": { "user_id": 4012 },
    "is_active": true,
    "use_bot_user": true,
    "bot_user": { "id": 873, "name": "Notification Bot", "avatar_url": "https://example.com/bot.png" },
    "token_hint": "a1b2",
    "url": "https://customer.monotree.com/api/open/v1/incoming/xxxxxxxxxxxx",
    "token": "xxxxxxxxxxxx",
    "created_at": "2026-06-13T10:00:00+00:00"
  }
}

GET and PUT responses are the same shape without url and token (those appear only on create).

Update

PUT accepts the same fields as create; only what you send is changed. Common uses: rename a webhook, repoint it (config), or pause it with "is_active": false (the trigger URL stops accepting deliveries). You cannot remove the bot from a direct_message webhook.

curl -X PUT https://customer.monotree.com/api/open/v1/incoming-webhooks/47 \
  -H "Authorization: Bearer mono_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{ "is_active": false }'

Revoke

POST /incoming-webhooks/{id}/revoke permanently deactivates the webhook and records revoked_at; the trigger URL stops working. The record and its delivery logs are kept for audit — there is no hard delete, mirroring the CMS.