API: Incoming Webhooks

Team Ryver API, Integration

Note: Webhooks have moved from the Admin Settings to the Integrations Menu

Intro

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 a 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. Define a new webhook and get the corresponding URL in Admin Settings > Webhooks. The Webhooks list view will show you all of your webhooks, as well as how many times they have been successfully used to create a message or post, or how many times an attempted webhook request has been denied.

Creating a Webhook

When you create a webhook, you are asked to select a format. Currently, the available formats are Ryver and Slack.

  • 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 or post, and which forum or team you want to create 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.

When you complete the webhook creation wizard, you will be given a URL that you can call to create a new chat message or post.

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, typically in their own JSON format. Unless those products currently support outputting 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 our next phase of webhook support, we will be creating transformations for a number of popular services. This will allow a direct integration between products. In the mean time, you would need to do your own transformation to the Ryver format and call the Ryver Incoming Webhook URL yourself.

Creating a chat message

In this article, we’ll focus on sending Ryver formatted webhooks. If you want to send a Slack formatted webhook payload, see the Slack API documentation.

In its most basic form, you can create a message simply by sending plain text to the provided URL. Here is a simple cURL 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!"

Or, you can use the Ryver JSON payload. Properties for the JSON payload include:

body (text), createSource (object), isEphemeral (boolean)

The createSource properties are:

displayName, avatar

You only need to supply the body property. createSource allows you to override the username/avatar you specified when creating the webhook. And isEphemeral allows you to send a chat message that only the webhook author can see. Ephemeral messages will not stay in chat history after you refresh.

Example JSON message (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"
  }
}

Creating a Topic

The payload for sending a topic webhook looks just like a chat webhook, except you would additionally add a subject field to your JSON payload. There are a couple of additional advanced properties that can be used to send an “shared email” topic into Ryver, which will be covered in a separate article.

Creating a Task

Here are the properties you can use in your JSON payload for tasks:

subject, body, dueDate, and completeDate

Custom Webhooks

We now support a new Custom Webhook type, where you can connect directly to another product’s outbound webhooks and provide your own transformation into Ryver format. Please see this article for more information.