Webhooks

Webhooks requires the SMALL plan or above.

Muut Webhooks are HTTP callbacks triggered by Muut events. They communicate with external web servers using POST requests in JSON format. Webhooks enable you to send custom event notifications to specified services (e.g. Twitter, Asana, or your own creation), which in turn trigger their own actions.

Muut events

Webhooks are configured to fire a notification upon the occurrence of one or more Muut events.

Webhooks UI

The available events are as follows:

  • post A new thread (with seed post) is created
  • reply A reply is made to an existing thread
  • remove A post or thread is removed
  • like A post or thread is liked
  • unlike A post or thread is unliked
  • spam A post or thread is marked as spam
  • unspam A post or thread is unmarked as spam
  • enter A user goes online
  • leave A user goes offline

HTTP request specification

When a Muut event of interest occurs, the Webhook sends a corresponding POST request to the service indicated in the URL field. The HTTP header and message body (payload) of the POST request are specified as follows:

HTTP Header

The POST requests sent to the servers contain the following special HTTP header fields:

  • X-Muut-Forum The unique Muut forum name
  • X-Muut-Signature The HMAC of the payload using the Webhook's secret as the key. Only present if secret is provided.

Payload

The payload of the POST request is in JSON, the native format used throughout the Muut architecture for communication / notification. The specific structure for different Muut event types are illustrated below.

User object
{
  "displayname": "John Doe",
  "img": "//domain.com/path/to/image.jpg",
  "path": "@johndoe"
}
Post
[
  "post", // name of the event
  {
   "path": "/goma/galleries:this-is-a-thread", // path to the thread
   "page": { "title": "Exhibitions" } // title of a channel
  },
  {
   "title": "This is a new reply", // title of the thread
   "body": [ "Head of the post", "Tail of the post"],
   "user": USER OBJECT
  }
]
Reply
[
  "reply", // event name
  "/goma/galleries:bar", // path to the thread
  {
   "body": [ "Head of the post", "Tail of the post"],
   "key": "some-reply", // reply key
   "user": USER OBJECT
  }
]
Like / unlike / spam / unspam / remove
[
  "like", // or any of "unlike", "spam", "unspam", "remove"
  "/goma/galleries:this-is-a-thread/some-reply", // path to target of action
  USER OBJECT
]
Enter / leave
[
  "enter", // or "leave"
  USER OBJECT
]

Development tools

To increase productivity in Webhooks development, you can make use of web services to which HTTP requests can be sent in order for you to inspect and debug efficiently. The services that we find useful are listed here for your reference.

RequestBin