Outgoing webhooks

Outgoing webhooks allow you to build or set up Meoyo integrations which are notified when certain types of messages are sent in Meoyo. When one of those events is triggered, the Meoyo server will send an HTTP POST payload to the webhook’s configured URL.

Outgoing webhooks can be used to power a wide range of Meoyo integrations. For example, the Meoyo Botserver is built on top of this API.

Create an outgoing webhook bot user

Desktop/Web

1. Navigate to the Bots tab of the Personal settings menu.
2. Click Add a new bot.
3. Set Bot type to Outgoing webhook.
4. Fill out the fields, with Endpoint URL set to the URL you’d like Meoyo to post to, and the outgoing webhook format you plan on using.
5. Click Add.

Triggering

There are currently two ways to trigger an outgoing webhook:

• @-mention the bot user in a channel. If the bot replies, 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, 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 Meoyo server by setting OUTGOING_WEBHOOKS_TIMEOUT_SECONDS in the server’s settings.

Replying with a message

Many bots implemented using this outgoing webhook API will want to send a reply message into Meoyo. Meoyo’s outgoing webhook API provides a convenient way to do that by simply returning an appropriate HTTP response to the Meoyo 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 dictionary 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:

{
    "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:

{
    "content": "Hey, we just received **something** from Meoyo!"
}

The content field should contain Meoyo-flavored Markdown.

Note that an outgoing webhook bot can use the Meoyo REST API with its API key in case your bot needs to do something else, like add an emoji reaction or upload a file.