Incoming webhooks

An incoming webhook is a private URL that lets an outside service, such as a CI system or a monitoring tool, post messages into one group chat. Chat owners and managers create and manage webhooks in the iPhone, Android and web apps.

Availability

The desktop app shows webhook messages but has no webhook settings. To create or manage webhooks, use the iPhone, Android or web app.

Who can manage webhooks

In a group chat, the owner and managers can create and manage webhooks. In a feed chat, only the owner can. Other members don’t see the webhook settings.

Create a webhook

1. Open the group, then open Chat info (the info icon).
2. Select Manage chat. Under Group Management (Feed Management in a feed chat), select Webhooks.
3. Select +, or Add Webhook if the chat has no webhooks yet.
4. On the Add Bot screen, fill in the fields described below, then select Create Bot.
5. In Webhook Created, select Copy URL.
6. Paste the URL into the outside service’s webhook settings.

The app calls a webhook a “bot” on these screens (Add Bot, Create Bot and the webhook’s page, Bot), but it’s not a bot account.

Field	What it’s for
Name *	Required. Identifies the webhook in the Webhooks list. Up to 100 bytes.
Description	Optional. Up to 500 bytes.
Display Name	The sender name on the webhook’s messages. Up to 32 bytes. If you leave it empty, messages show Webhook.
Avatar	The picture shown with the webhook’s messages.

In byte limits, each English letter, digit or space counts as 1 byte, and accented letters and most other scripts take 2 or 3 bytes. A typical emoji takes 4 bytes, and flags or emoji with a skin tone take more. If a value is too long, creating the webhook fails. You can’t change the name, description or display name later, only the picture.

Keep the URL secret

The URL is shown only once, and anyone who has it can post messages in your chat. Store it in the outside service’s secret settings and don’t share it in a chat. If it leaks, replace it.

For the request format, limits and errors, see Incoming webhooks API.

Manage a webhook

Open Chat info > Manage chat > Webhooks. The list shows each webhook’s name, whether it’s ACTIVE or INACTIVE, how many messages it has posted and when it was created. Select a webhook to open its page, titled Bot:

• Statistics shows Messages Sent, Last Used and Created.
• Configuration shows the Display Name and the Rate Limit: the most messages the webhook accepts per minute and per hour. Posts over the limit are refused. You can’t change the rate limit in the app.

Switch a webhook off or on

Use the switch next to Active on the webhook’s page; it reads Inactive while the webhook is off. While the webhook is inactive, posts to its URL are refused and nothing appears in the chat. Switch it back on to accept posts at the same URL.

Replace the URL

1. On the webhook’s page, select Rotate Token, then Rotate to confirm.
2. In New Bot URL, select Copy URL.
3. Give the outside service the new URL.

The old URL stops working immediately, and the new one is also shown only once.

Change the picture

Select the picture on the webhook’s page and choose a new one.

Delete a webhook

On the webhook’s page, select the trash icon (Delete), then Delete in the Delete Bot dialog. The URL stops working, and you can’t undo this.

How webhook messages look

• Each post appears as a new message in the main chat, not in a thread, with the display name, the picture and a BOT label.
• The outside service can set a different name or picture for each message.
• Webhooks post plain text. They can’t send files, interactive cards or thread replies.
• Members are notified as for other messages, unless they’ve muted the chat. The person who created the webhook isn’t notified about its messages.
• Bots don’t receive webhook messages, so a webhook post never triggers a bot.

Related

• Incoming webhooks API
• Use bots in chats
• Bots and agents