Incoming hooks

Ready-made integrations that need no code of your own. A hook is a secret URL bound to one of the bot's chats and to a format; whatever is posted to it, the bot writes to the chat.

Turning hooks on

Set HOOKS_URL to the gateway's public address and BOT_OWNERS to the account ids allowed to manage hooks. Publish only the /hooks/ path to the internet.

environment:
  HOOKS_URL: https://bot.example.com
  BOT_OWNERS: u7f…,u2c…
  UPDATES: "off"   # if the bot only sends

To find your account id, write anything to the bot: to people not in BOT_OWNERS it answers with their id.

Creating a hook from the chat

An owner writes to the bot in a private chat, or in a group the bot was added to:

Command	What it does
/hook alertmanager · /hook gitlab · /hook text	Creates a hook for this chat and answers with its URL. In a group the URL is sent to the owner privately.
/hooks	Lists the chat's hooks.
/unhook <id>	Removes a hook.

The bot declares these commands itself if it has no commands of its own.

Creating a hook through the API

POST /v1/hooks
{"chat_id": "g3a…", "format": "alertmanager"}

{"id": "h1…", "chat_id": "g3a…", "format": "alertmanager", "ts": 1791370000000,
 "url": "https://bot.example.com/hooks/…"}

The URL is shown only once: the gateway keeps only a hash of the secret. GET /v1/hooks?chat= lists hooks, DELETE /v1/hooks/{id} removes one.

Posting to a hook

POST /hooks/<secret> needs no token; the body is up to 1 MB.

Answer	Meaning
200	Written to the chat.
404	No such hook.
410	The chat is gone.
502	The message could not be sent; Alertmanager and GitLab retry by themselves.

Formats

INFO

The bot's own replies and the hook messages are in Russian for now.

Format	Accepts	Writes to the chat
alertmanager	Alertmanager webhook_configs (version 4)	🔥 <alertname> · N and up to 10 lines "summary (severity, instance or namespace/pod)"; when resolved, ✅ … in reply to the firing message.
gitlab	GitLab Pipeline events (other events get 200 and are ignored). If X-Gitlab-Token is set, it must equal the secret.	Failed and canceled pipelines (project, branch, commit, author, failed jobs, link); a success after a failure on the same branch as "fixed". Other successes are not reported.
text	text/plain as is, or JSON {"text": "…"}	The text.

Alertmanager

receivers:
  - name: mailbees
    webhook_configs:
      - url_file: /etc/secrets/mailbees-hook   # the hook URL contains the secret
        send_resolved: true

GitLab

Project → Settings → Webhooks: paste the URL, tick Pipeline events.

Anything else

curl -d 'Backup finished' https://bot.example.com/hooks/<secret>