SectionIncoming webhooks

Incoming webhooks

How to post a message to a Syncra channel with one HTTP request, from getting the webhook address to the responses and limits.

An incoming webhook is a secret address tied to one channel. Your service sends a POST request with some text to it, and a bot posts that text in the channel. You need no bot key and no authorization header, which makes it a good fit for build, payment and outage notifications. A workspace owner or admin creates the address: workspace settings, the Bots tab, the bot’s page, the Incoming webhooks section. A webhook belongs to a bot, so you need a bot first: Bots.

Get the address

  1. Open the workspace settings, go to the Bots tab and open the bot’s page.
  2. In Incoming webhooks, pick a channel in the Channel field. Public and private channels both work. Direct messages cannot be picked.
  3. Fill in Name (optional) if you like, for example “Alerts from Grafana”. The name helps you tell webhooks apart in the list.
  4. Press Create webhook. The bot joins the channel automatically.
  5. The webhook’s row now shows the full address. Copy it with the button next to it.

The address looks like this: https://ai-syncra.ru/api/webhooks/whk_.... The whk_... part is the secret: anyone who knows the address can post to the channel. Treat it like a password and keep it out of public code. The address stays visible in settings for as long as the webhook exists, so you can copy it again later.

One bot can have several webhooks. Each one is tied to a single channel.

Send a message

POST /api/webhooks/:token

Posts text in the channel the webhook is tied to. The bot is the author of the message.

Path parameter:

Parameter Type Required Description
token string yes The secret part of the address, starts with whk_. Copy the whole address from settings.

Request body, JSON:

Field Type Required Description
text string yes The message text, 1 to 4000 characters.

The request has no other fields. Syncra ignores everything except text. No Authorization header is needed.

curl -X POST "https://ai-syncra.ru/api/webhooks/whk_..." \
  -H "Content-Type: application/json" \
  -d '{"text":"Build 142 passed"}'

Response 200 OK:

{
  "ok": true,
  "messageId": "..."
}

messageId is the id of the posted message. With it the bot can edit or delete that message, or reply to it in a thread, through the bot API: Messages in the bot API.

Errors

An error body is JSON with an error field. Its text is English by default. If the request carries an Accept-Language: ru header, the standard error texts come back in Russian, so build your logic on the status code, not on the text.

Status Body When
400 {"error":"Invalid JSON"} The request body does not parse as JSON.
403 {"error":"Forbidden"} A web page on another site sent the request: its Origin or Referer header names a different site.
404 {"error":"Not found"} The address is unknown, the webhook was deleted, or the bot is turned off.
422 {"error":"Validation error","details":{...}} text is missing, empty, longer than 4000 characters, or not a string.
429 {"error":"Too many requests"} The request limit for this webhook is exceeded.

A 422 response when the body has no text:

{
  "error": "Validation error",
  "details": {
    "formErrors": [],
    "fieldErrors": {
      "text": ["Required"]
    }
  }
}

In fieldErrors the key is the field name and the value is a list of reasons. The wording of a reason comes from the validation library. Rely on the status and the field name, not on the reason text.

Limits

  • At most 60 requests per 60 seconds for one webhook. The 60-second window starts with the first request. Requests with a bad body count too.
  • A 429 response carries no Retry-After or X-RateLimit-* headers. Wait up to a minute and try again.
  • Send the request from a server. A request from a browser page on another site does not go through.
  • A webhook posts text only. You cannot attach files.
  • Each request posts a new message. A webhook cannot reply in a thread.
  • The message shows the bot’s name and avatar. The request cannot set a different name or avatar.
  • @channel and @here in the text notify nobody.
  • A webhook posts to the one channel chosen when it was created. To post to another channel, create a new webhook.
  • Webhooks cannot post to direct messages.

Turn off or delete a webhook

To close an address for good, press Delete in the webhook’s row and confirm. Requests to that address start getting 404 at once. A deleted address cannot be restored: create a new webhook and replace the address in your service.

To stop everything at once, turn off the Bot enabled switch on the bot’s page. While the bot is off, its webhooks answer 404, Syncra rejects its keys and its event subscriptions send nothing.

When a webhook is not enough

If your service needs to reply in threads, attach files, read messages or write direct messages, use a bot key and the bot API:

If you need the opposite direction, hearing about things that happen in Syncra, set up event subscriptions. The full list of limits is on the What exists and what does not page.