Quick start

Get your personal webhook in a minute and start receiving notifications in Telegram.

Get your hook

Open @ThookBot and send /start. The bot answers with your personal endpoints and a secret. The secret is hidden as a spoiler: tap it to reveal it, or use the Copy secret key button under the message.

Keep it private. The URL and the secret are all that is needed to post in your chat. Copy them, then delete the bot message from the group or channel.

In groups only the administrators can use /start, /rotate and /cleanup: the bot does not show the endpoints to other members. Channel posts can only be written by administrators anyway.

The endpoint

Every service has its own endpoint and the same unique path:

https://thook.altr.dev/hooks/{service}/{unique_path}

Secret

The bot gives you a secret key. It authenticates every call, so Thook knows the request is really yours:

• GitHub: use it as the webhook Secret. Thook verifies the X-Hub-Signature-256 HMAC.
• GitLab: use it as the Secret token. It arrives in X-Gitlab-Token.
• Gitea and Forgejo: use it as the Secret. Thook verifies the HMAC of the body (X-Gitea-Signature, X-Forgejo-Signature or X-Hub-Signature-256).
• Bitbucket: use it as the Secret. Thook verifies the X-Hub-Signature HMAC.
• Netlify: use it as the JWS secret token. Thook verifies the signed request.
• Generic: send it in the X-Webhook-Signature header.

Rotate the secret key

If the secret was exposed, for example because the bot message stayed visible in a group, generate a new one:

1. Send /rotate. The bot explains what will happen and changes nothing yet.
2. Send /rotate confirm to replace the key (in channels /rotate@ThookBot confirm).

The webhook URLs do not change, only the secret key does. Every service or script that used the old key gets 401 until you update it with the new one.

Groups that used Thook before this feature: the endpoints and the secret may still be in the chat history, visible to every member. Thook does not rotate anything on its own: if that is your case, an administrator should send /rotate and then /rotate confirm.

Workflows, pipelines and deploys

Something that runs for a while sends more than one event: started, running, then the result. Thook keeps them in a single message: the first step is sent, the next steps edit that message instead of adding a new one. The result (passed, failed, cancelled) is always a new message, so your phone notifies you: an edit does not.

Everything else (a push, an issue, a comment, a release…) is one message per event.

By default the message of the steps stays in the chat after the result. To keep the chat tidy, send /cleanup on and Thook deletes that message when the result arrives, so only the result stays.

In channels use /cleanup@ThookBot on. In groups only the administrators can change it. The setting is for the whole chat and applies to every service.

A run is followed for 7 days. A step that arrives after the result is ignored, and a run that starts again (a re-run) gets a new message.

What the notifications show

Every notification has the same shape: the event and the service as the title, the details with one icon per line, who did it, and a link to the event as the last line. Texts written by a person, like an error or a description, are in italics.

The icon of the title tells the state at a glance:

The icon of each line tells what it is:

Responses

Events Thook does not support are accepted with 202 and ignored, so a service never keeps retrying them.

Troubleshooting

• 401: the secret does not match. Ask the bot for /start again and copy it without spaces.
• 404: check the unique path and that you used the right service in the URL.
• Nothing arrives but the status is 202: the event type is not supported, or the bot was removed from the chat or blocked. Add it again and send /start.
• Groups and channels: the bot must be a member of the group, or an administrator of the channel.