Intro to webhooks
Use Incoming Webhooks to create new chat messages, topics or tasks in Ryver just by sending a plain text or JSON payload to a URL over HTTPS. Webhooks are commonly used for implementing integrations with other products and services. You can use markdown to format the messages to include tables and other rich display options.
If you are an Administrator in your organization, you will see “Integrations” in the menu that pops up when you click on your username at the bottom of the left navigation bar. This menu item will bring up the Integrations dialog, where you can manage your webhooks.
Note: Outbound webhooks are now in private beta. Please let Support know if you would like to have access.
Creating an incoming webhook
When you create an incoming webhook, you are asked to select a format. Currently, the available formats are Ryver, Slack and Custom. We’ll cover custom webhooks in the next article.
A Ryver-formatted webhook uses a predefined Ryver JSON format in the payload, or it can be a simple plain text payload. If you create a Slack-formatted webhook, you can provide a Slack Incoming Webhook JSON payload. Ryver will convert it, and also convert any Slack formatting to the Ryver-flavored markdown. This means if you have migrated to Ryver from Slack and were using Incoming Webhooks there, you can simply replace the URL with your Ryver webhook URL.
Next, select whether you want the webhook to create a chat message, topic or task, and which forum or team you want to create the content in. You can optionally provide a description of the webhook, and a display name and avatar that the content will be “from” in the Ryver client. If you select an avatar and/or name in the UI, that will be the default for the webhook, but you can also over-ride it in the payload that you pass for each call to the webhook URL.
When you complete the webhook creation wizard, you will be given a URL that you can call to create a new chat message, topic or task.
Note: There are a lot of products and services out there that support “Outbound” webhooks, in which they will output data to a URL that you give them (the incoming webhook URL), typically in their own JSON format. Unless those products currently support outputting to plain text, or to the Slack format, you will not be able to simply plug a Ryver Incoming Webhook URL into those products, as their format will not match the expected format in Ryver. In these cases, you will want to create a Custom Webhook
Webhook payload format
Chat Message
In its simplest form, when you create a “Plain Text/Ryver” webhook to create a chat message, you can just pass the plain text message text that you want displayed in the Ryver chat message. For example:
curl -X "POST" "https://example.ryver.com/application/webhook/Il9V1sSlixOvIU1" \
-H "Content-Type: text/plain; charset=utf-8" \
-d "**Hello World!** This is my first webhook message!"
However, if you use the Ryver JSON format, there are some additional message options available to you.
JSON Properties:
- body (text) - The body of the message.
- createSource (object) - Optional display-name/avatar to use for this chat message in the Ryver chat history UI.
- createSource properties: displayName (string), avatar (string URL)
- isEphemeral (boolean) - Optional flag to indicate that you want the message to be ephemeral, meaning it will be displayed to people in the Ryver client when the message comes in, but the message will not be stored in chat history. Once a user refreshes, the message will go away.
Example (sent from Paw for Mac):
POST /application/webhook/Il9V1sSlixOvIU1
HTTP/1.1
Content-Type: application/json; charset=utf-8
Host: example.ryver.com
Connection: close
User-Agent: Paw/3.0.15 (Macintosh; OS X/10.11.3) GCDHTTPRequest
{
"body":"Sending chat message from Paw...",
"createSource":{
"displayName":"Paw for Mac",
"avatar":"https://pbs.twimg.com/profile_images/758669027166261249/UKsGtXHO.jpg"
}
}
Topic
The Topic webhook format is similar to a chat message, but without the ephemeral option, and with the addition of a subject json property.
Example (sent from Paw for Mac):
POST /application/webhook/Il9V1sSlixOvIU1
HTTP/1.1
Content-Type: application/json; charset=utf-8
Host: example.ryver.com
Connection: close
User-Agent: Paw/3.0.15 (Macintosh; OS X/10.11.3) GCDHTTPRequest
{
"subject": "This is my topic subject",
"body":"This is my topic description, displayed as the first entry in the topic discussion.",
"createSource":{
"displayName":"Paw for Mac",
"avatar":"https://pbs.twimg.com/profile_images/758669027166261249/UKsGtXHO.jpg"
}
}
Task
When creating a task via webhook, the JSON payload looks similar to the topic payload, but adds dueDate and completeDate properties. Populate completeDate if you want the task to be created in an already completed state.
Example (sent from Paw for Mac):
POST /application/webhook/Il9V1sSlixOvIU1
HTTP/1.1
Content-Type: application/json; charset=utf-8
Host: example.ryver.com
Connection: close
User-Agent: Paw/3.0.15 (Macintosh; OS X/10.11.3) GCDHTTPRequest
{
"subject": "This is my topic subject",
"body":"This is my topic description, displayed as the first entry in the topic discussion.",
"dueDate": "2018-06-30",
"createSource":{
"displayName":"Paw for Mac",
"avatar":"https://pbs.twimg.com/profile_images/758669027166261249/UKsGtXHO.jpg"
}
}