Zulip server and web application. Open-source team chat that helps teams stay productive and focused.
---
title: Outgoing webhooks
---
import {TabItem, Tabs} from "@astrojs/starlight/components";
import FlattenedSteps from "../../components/FlattenedSteps.astro";
import NavigationSteps from "../../components/NavigationSteps.astro";
Outgoing webhooks allow you to build or set up Zulip integrations
which are notified when certain types of messages are sent in Zulip.
When one of those events is [triggered](#triggering), the Zulip server
will send an HTTP POST [payload](/api/outgoing-webhook-payload) to the
webhook's configured URL.
Outgoing webhooks can be used to power a wide range of Zulip
integrations. For example, the [Zulip Botserver](/help/deploying-bots#zulip-botserver)
is built on top of this API.
## Create an outgoing webhook bot user
<Tabs>
<TabItem label="Desktop/Web">
<FlattenedSteps>
<NavigationSteps target="settings/your-bots" />
1. Click **Add a new bot**.
1. Set **Bot type** to **Outgoing webhook**.
1. Fill out the fields, with **Endpoint URL** set to the URL you'd like
Zulip to post to, and the outgoing webhook [format](/api/outgoing-webhook-payload)
you plan on using.
1. Click **Add**.
</FlattenedSteps>
</TabItem>
</Tabs>
## Triggering
There are currently two ways to trigger an outgoing webhook:
* **@-mention** the bot user in a channel. If the bot
[replies](#replying-with-a-message), its reply will be sent to that
channel and topic.
* **Send a direct message** with the bot user as one of the recipients.
If the bot [replies](#replying-with-a-message), its reply will be
sent to that direct message conversation.
## Timeouts
The remote server must respond to a `POST` request in a timely manner.
The default timeout for outgoing webhooks is 10 seconds, though this
can be configured by the administrator of the Zulip server by setting
`OUTGOING_WEBHOOKS_TIMEOUT_SECONDS` in the [server's
settings](https://zulip.readthedocs.io/en/latest/subsystems/settings.html#server-settings).
## Replying with a message
Many bots implemented using this outgoing webhook API will want to
send a reply message into Zulip. Zulip's outgoing webhook API
provides a convenient way to do that by simply returning an
appropriate HTTP response to the Zulip server.
A correctly implemented bot will return a JSON object containing one
of two possible formats, described below.
### Example response payloads
If the bot code wants to opt out of responding, it can explicitly
encode a JSON object that contains `response_not_required` set
to `True`, so that no response message is sent to the user. (This
is helpful to distinguish deliberate non-responses from bugs.)
Here's an example of the JSON your server should respond with if
you would not like to send a response message:
```json
{
"response_not_required": true
}
```
Here's an example of the JSON your server should respond with if
you would like to send a response message:
```json
{
"content": "Hey, we just received **something** from Zulip!"
}
```
The `content` field should contain [Zulip-flavored Markdown](/help/format-your-message-using-markdown).
Note that an outgoing webhook bot can use the [Zulip REST
API](/api/rest) with its API key in case your bot needs to do
something else, like add an emoji reaction or upload a file.