Incoming Webhooks

An incoming webhook is an address that lets external tools such as CI pipelines, monitoring tools, and in-house scripts post a message to a channel with a single HTTP request. This page covers how to send a request, what comes back, and what is limited. The formatting and tokens you can use in the body are in the Message Format Reference, and ready-to-copy samples are in Examples. To let a tool read the channel with the same URL and secret, see Reading a Channel.

Creating a webhook

A channel admin creates webhooks from the channel screen. A channel can have several webhooks, so creating one per tool lets you tell at a glance which tool sent a message.

1. Open Channel settings from the channel menu to bring up Edit channel. Click Webhooks at the bottom to open Manage webhooks.

2. Click + Create and enter the name to show in the channel under Webhook profile. Names must be unique within the channel. The profile image is optional. Messages are posted under this name and image.

3. If the tool also needs to read this channel, turn on Allow reading channel messages. It is off by default. When it is on, the same URL and secret can read the channel. You can change it after creation too.

4. Click Save. You get the URL, the secret, and a ready-to-paste curl command (Send a test request).

When creation finishes you receive two values.

On a self-hosted installation, your server address takes the place of https://collabops.ai. Use the URL exactly as shown on the creation screen.

Turn on, turn off, rename, delete

Each card in Manage webhooks has an on/off switch and a ⋯ menu. The ⋯ menu offers Delivery history, Allow reading channel messages, Rename and Delete. Any channel member can view the delivery history. Only channel admins can change the rest.

Request format

curl -X POST "https://collabops.ai/api/v2/integration/webhook/<token>" \
  -H "Authorization: Bearer <secret>" \
  -H "Content-Type: application/json" \
  -d '{"text": "**Deployed** `web` 0.4.2"}'

Body — text and blocks

The body uses exactly one of two forms. Sending both text and blocks, or neither, returns 422.

The text form

The blocks form

Block types and their shapes are in the Message Format Reference.

Response

Once the request is accepted, the webhook answers 202 Accepted right away without waiting for the post. Posting to the channel happens asynchronously afterwards.

{"delivery_id": 1234, "deduped": false}

Error responses

On failure you get JSON shaped like the following. error.title holds the reason, and error.request_id is the trace ID to quote when asking for support. The same trace ID is also sent in the X-Request-Id response header.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "title": "요청 형식이 올바르지 않습니다: exactly one of text or blocks is required",
    "request_id": "3f1c9a52-8e0b-4c1d-9f7a-2b6e4d8c1a90",
    "upstream_status": 422
  }
}

Limits

Blocks are counted after conversion. For the text form, that is the count after the Markdown is turned into blocks. Each paragraph, heading, and list item is one block, and each table cell is one block, so a 3-column, 10-row table alone is 30 blocks. A body that produces no blocks at all, such as whitespace-only text, is also rejected with 422.

Split long reports into a thread rather than packing them into one message.

Preventing duplicates

When a network error swallows the response, the sending tool ends up retrying the same request. Put a value unique to each notification in the Idempotency-Key header and the message is posted only once, however many times it arrives with that key. The repeat response returns deduped: true and the first delivery_id.

Without a key, every request becomes a new message. Build the key so the same notification always yields the same value, for example deploy-3f9c2a71-success from the commit SHA and the event type. Rejected requests such as 401 or 422 do not claim the key, so after fixing the body you can resend with the same key and it is processed normally.

Threads

Put the delivery_id from a response into the next request's parent_delivery_id and the new message is posted as a reply to it. You do not need to know internal chat message IDs.

Checking delivery results

Each card in Manage webhooks shows the Last delivery status, and Delivery history in the ⋯ menu lists every request, newest first. Each entry shows when it arrived, its status, the body format (Text or Blocks) and whether it was a thread reply. Posted entries have View message, which opens that message in the channel. Rejected entries show the same English reason that follows the colon in error.title, and entries that failed body validation have Show payload so you can see the JSON that was sent.

A 404 for an unknown webhook, a 413 for requests over 1 MiB and temporary 5xx errors are not recorded, so check the response code in the sender's logs.