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 Manage webhooks.

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

  2. If this is the space's first webhook, you are prompted to provide a webhook name and avatar URL. If the space already has webhooks, click Add another.

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

  4. Click SAVE.

Copy and save the webhook URL

From the Manage webhooks modal, find your webhook 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:

http_obj.request(
  uri=THE_SAVED_URL,
  method='POST',
  headers=message_headers,
  body=dumps(bot_message),
)

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

Limits and considerations

As you configure webhooks, take note of these limits and considerations:

  • 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.

  • Because Manage webhooks is only available from a web browser, webhooks must be set up from the Chat web app. Webhooks are not configurable from the Chat mobile app.