Using incoming webhooks

Incoming webhooks let you send asynchronous messages into Google Chat from applications that aren't bots themselves. For example, you can configure a monitoring application to notify oncall personnel on Google Chat when a server goes down. Incoming webhooks serve as a quick and easy way to integrate with existing workflows such as these without the overhead of writing entire bot applications.

Applications using incoming webhooks have several restrictions:

  • They cannot be published, so they can't be installed in other chat spaces.
  • They are not conversational since the webhook mechanism only works for inbound messages.

Setting up an incoming webhook

To set up and use a webhook is straightforward:

  1. Define the incoming webhook in Google Chat, provide a name and optionally an avatar for the bot.
  2. Copy the system-generated URL and save it for your bot to use
  3. Your bot can send messages to that URL, using the message format elements.

These steps are described in more detail below.

Define an incoming webhook

From the chat space menu:

  1. Select Configure Webhooks

    A dialog appears that lists any incoming webhooks already defined for the space.

  2. Click on ADD WEBHOOK.

  3. Fill in the name field and optionally the avatar URL field.

  4. Click SAVE.

Copy and save the webhook URL

In the Configure Webhooks screen shown above, find your webhook in the list and click the copy icon to copy the webhook URL.

Save this URL in your bot's source code or configuration so that it can be used as a message destination.

Send messages to the chat space

Construct an HTTP message and send it to the saved URL as shown below:


For a more complete code example, see the Incoming Webhooks quickstart.


If only select organizational units (OUs) in your domain have bots enabled, incoming webhooks created in a space will fail with the following error:

  "error": {
    "code": 403,
    "message": "The caller does not have permission",
    "status": "PERMISSION_DENIED"

Incoming webhooks do work in direct messages, but only when all users have bots enabled.