API Reference version 2

Webhooks

Webhooks can be registered by a user or integration to receive a notification of an event. They can currently only be registered against a specific room via the the REST API.

Here's an example of a webhook declared in an add-on descriptor:

"capabilities": {
  ...
  "webhook": [
    {
      "url": "https://addon.example.com/echo",
      "pattern": "^/[eE][cC][hH][oO]",
      "event": "room_message",
      "authentication": "jwt",
      "name": "Echo"
    }
  ]
]

Reference

Type Property Description Required?
string authentication

The authentication method for this webhook

Valid values: jwt, none.

Defaults to 'none'.

string event

The event to listen for

Valid values: room_archived, room_created, room_deleted, room_enter, room_exit, room_file_upload, room_message, room_notification, room_topic_change, room_unarchived.

Required
string key

Unique key (in the context of the integration) to identify this webhook.

Valid length range: 1 - 40.

string name

The label for this webhook

string pattern

The regular expression pattern to match against messages. Only applicable for message events.

string url

The URL to send the webhook POST to

Required

Webhook Authentication

Webhooks declared by an add-on can optionally receive a JWT authenticating the request. The JWT is sent in the Authorization header and has the same structure as the JWT sent in the signed_request query parameter for configuration pages and other UI elements:

POST /echo HTTP/1.1
Host: addon.example.com
Authorization: JWT eyJhbGciOiAiSFMyNTYiLCAi...
Content-Length: 646
Content-Type: application/json

Webhook Responses

The receiver of a webhook may optionally return a JSON response, in which case it will be sent as a notification to the room. This behaves the same as using the Send room notification API. The format of the JSON is the same as you send in the request body for Send room notification.

Webhook Events

The following are the available webhook events and the information they will send to the receiver.

room_archived

Webhook for a room archival

The event is sent as an HTTP POST with a JSON-encoded body containing:

Type Property Description Required?
string event

The webhook event name.

Required
object item

The event data.

Required
object room

The room that was archived.

Required
integer id

ID of the room.

Required
boolean is_archived

Whether or not this room is archived.

Required
object links

URLs to retrieve room information

Required
string members

The URL to use to retrieve members for this room. Only available for private rooms. Note this link will be made available to public room from Dec 1, 2016

string participants

The URL to use to retrieve participants for this room

Required
string self

The URL to use to retrieve the full room information

Required
string webhooks

The URL to use to retrieve webhooks registered for this room

Required
string name

Name of the room.

Required
string privacy

Privacy setting

Valid values: public, private.

Required
string version

An etag-like random version string.

Required
obj | obj | str sender

The member that archived the room.

Required
object [sender, object 1]

An object with the following properties.

Required
integer id

The user ID

Required
object links

URLs to retrieve user information

Required
string self

The link to use to retrieve the user information

Required
string mention_name

User's @mention name

Required
string name

The display user name

Required
string version

An etag-like random version string.

Required
object [sender, object 2]

An object with the following properties.

Required
array allowed_scopes

List of possible scopes that are allowed for requested tokens

string id

ID of the client.

Required
object links

URLs to retrieve oauth client information

Required
string self

The URL to use to retrieve the full oauth client information

Required
string name

The name of the client, if any

object room

The room, if specified, that this client is restricted to.

May be null.

Required
integer id

ID of the room.

Required
boolean is_archived

Whether or not this room is archived.

Required
object links

URLs to retrieve room information

Required
string members

The URL to use to retrieve members for this room. Only available for private rooms. Note this link will be made available to public room from Dec 1, 2016

string participants

The URL to use to retrieve participants for this room

Required
string self

The URL to use to retrieve the full room information

Required
string webhooks

The URL to use to retrieve webhooks registered for this room

Required
string name

Name of the room.

Required
string privacy

Privacy setting

Valid values: public, private.

Required
string version

An etag-like random version string.

Required
string oauth_client_id

The oauth client id that registered this webhook, if applicable.

integer webhook_id

The unique identifier for this webhook registration.

Required

room_created

Webhook for a room creation

The event is sent as an HTTP POST with a JSON-encoded body containing:

Type Property Description Required?
string event

The webhook event name.

Required
object item

The event data.

Required
object room

The room that was created.

Required
integer id

ID of the room.

Required
boolean is_archived

Whether or not this room is archived.

Required
object links

URLs to retrieve room information

Required
string members

The URL to use to retrieve members for this room. Only available for private rooms. Note this link will be made available to public room from Dec 1, 2016

string participants

The URL to use to retrieve participants for this room

Required
string self

The URL to use to retrieve the full room information

Required
string webhooks

The URL to use to retrieve webhooks registered for this room

Required
string name

Name of the room.

Required
string privacy

Privacy setting

Valid values: public, private.

Required
string version

An etag-like random version string.

Required
obj | obj | str sender

User who created the room.

Required
object [sender, object 1]

An object with the following properties.

Required
integer id

The user ID

Required
object links

URLs to retrieve user information

Required
string self

The link to use to retrieve the user information

Required
string mention_name

User's @mention name

Required
string name

The display user name

Required
string version

An etag-like random version string.

Required
object [sender, object 2]

An object with the following properties.

Required
array allowed_scopes

List of possible scopes that are allowed for requested tokens

string id

ID of the client.

Required
object links

URLs to retrieve oauth client information

Required
string self

The URL to use to retrieve the full oauth client information

Required
string name

The name of the client, if any

object room

The room, if specified, that this client is restricted to.

May be null.

Required
integer id

ID of the room.

Required
boolean is_archived

Whether or not this room is archived.

Required
object links

URLs to retrieve room information

Required
string members

The URL to use to retrieve members for this room. Only available for private rooms. Note this link will be made available to public room from Dec 1, 2016

string participants

The URL to use to retrieve participants for this room

Required
string self

The URL to use to retrieve the full room information

Required
string webhooks

The URL to use to retrieve webhooks registered for this room

Required
string name

Name of the room.

Required
string privacy

Privacy setting

Valid values: public, private.

Required
string version

An etag-like random version string.

Required
string oauth_client_id

The oauth client id that registered this webhook, if applicable.

integer webhook_id

The unique identifier for this webhook registration.

Required

room_deleted

Webhook for a room deletion

The event is sent as an HTTP POST with a JSON-encoded body containing:

Type Property Description Required?
string event

The webhook event name.

Required
object item

The event data.

Required
object room

The room that was deleted.

Required
integer id

ID of the room.

Required
boolean is_archived

Whether or not this room is archived.

Required
object links

URLs to retrieve room information

Required
string members

The URL to use to retrieve members for this room. Only available for private rooms. Note this link will be made available to public room from Dec 1, 2016

string participants

The URL to use to retrieve participants for this room

Required
string self

The URL to use to retrieve the full room information

Required
string webhooks

The URL to use to retrieve webhooks registered for this room

Required
string name

Name of the room.

Required
string privacy

Privacy setting

Valid values: public, private.

Required
string version

An etag-like random version string.

Required
obj | obj | str sender

The member that deleted the room.

Required
object [sender, object 1]

An object with the following properties.

Required
integer id

The user ID

Required
object links

URLs to retrieve user information

Required
string self

The link to use to retrieve the user information

Required
string mention_name

User's @mention name

Required
string name

The display user name

Required
string version

An etag-like random version string.

Required
object [sender, object 2]

An object with the following properties.

Required
array allowed_scopes

List of possible scopes that are allowed for requested tokens

string id

ID of the client.

Required
object links

URLs to retrieve oauth client information

Required
string self

The URL to use to retrieve the full oauth client information

Required
string name

The name of the client, if any

object room

The room, if specified, that this client is restricted to.

May be null.

Required
integer id

ID of the room.

Required
boolean is_archived

Whether or not this room is archived.

Required
object links

URLs to retrieve room information

Required
string members

The URL to use to retrieve members for this room. Only available for private rooms. Note this link will be made available to public room from Dec 1, 2016

string participants

The URL to use to retrieve participants for this room

Required
string self

The URL to use to retrieve the full room information

Required
string webhooks

The URL to use to retrieve webhooks registered for this room

Required
string name

Name of the room.

Required
string privacy

Privacy setting

Valid values: public, private.

Required
string version

An etag-like random version string.

Required
string oauth_client_id

The oauth client id that registered this webhook, if applicable.

integer webhook_id

The unique identifier for this webhook registration.

Required

room_enter

Webhook for an entering room member

The event is sent as an HTTP POST with a JSON-encoded body containing:

Type Property Description Required?
string event

The webhook event name.

Required
object item

The event data.

Required
object room

The room the member is entering.

Required
integer id

ID of the room.

Required
boolean is_archived

Whether or not this room is archived.

Required
object links

URLs to retrieve room information

Required
string members

The URL to use to retrieve members for this room. Only available for private rooms. Note this link will be made available to public room from Dec 1, 2016

string participants

The URL to use to retrieve participants for this room

Required
string self

The URL to use to retrieve the full room information

Required
string webhooks

The URL to use to retrieve webhooks registered for this room

Required
string name

Name of the room.

Required
string privacy

Privacy setting

Valid values: public, private.

Required
string version

An etag-like random version string.

Required
object sender

The member that is entering.

Required
integer id

The user ID

Required
object links

URLs to retrieve user information

Required
string self

The link to use to retrieve the user information

Required
string mention_name

User's @mention name

Required
string name

The display user name

Required
string version

An etag-like random version string.

Required
string oauth_client_id

The oauth client id that registered this webhook, if applicable.

integer webhook_id

The unique identifier for this webhook registration.

Required

room_exit

Webhook for an exiting room member

The event is sent as an HTTP POST with a JSON-encoded body containing:

Type Property Description Required?
string event

The webhook event name.

Required
object item

The event data.

Required
object room

The room the member is exiting.

Required
integer id

ID of the room.

Required
boolean is_archived

Whether or not this room is archived.

Required
object links

URLs to retrieve room information

Required
string members

The URL to use to retrieve members for this room. Only available for private rooms. Note this link will be made available to public room from Dec 1, 2016

string participants

The URL to use to retrieve participants for this room

Required
string self

The URL to use to retrieve the full room information

Required
string webhooks

The URL to use to retrieve webhooks registered for this room

Required
string name

Name of the room.

Required
string privacy

Privacy setting

Valid values: public, private.

Required
string version

An etag-like random version string.

Required
object sender

The member that is exiting.

Required
integer id

The user ID

Required
object links

URLs to retrieve user information

Required
string self

The link to use to retrieve the user information

Required
string mention_name

User's @mention name

Required
string name

The display user name

Required
string version

An etag-like random version string.

Required
string oauth_client_id

The oauth client id that registered this webhook, if applicable.

integer webhook_id

The unique identifier for this webhook registration.

Required

room_file_upload

Webhook for room file upload

The event is sent as an HTTP POST with a JSON-encoded body containing:

Type Property Description Required?
string event

The webhook event name.

Required
object item

The event data.

Required
object file

Uploaded file data

Required
string name

The name of the file

Required
integer size

The size of the file in bytes

Required
string thumb_url

The URL of the thumbnail if it exists

string url

The URL of the file

Required
object room

The room the message was sent to.

Required
integer id

ID of the room.

Required
boolean is_archived

Whether or not this room is archived.

Required
object links

URLs to retrieve room information

Required
string members

The URL to use to retrieve members for this room. Only available for private rooms. Note this link will be made available to public room from Dec 1, 2016

string participants

The URL to use to retrieve participants for this room

Required
string self

The URL to use to retrieve the full room information

Required
string webhooks

The URL to use to retrieve webhooks registered for this room

Required
string name

Name of the room.

Required
string privacy

Privacy setting

Valid values: public, private.

Required
string version

An etag-like random version string.

Required
object sender

The member that uploaded the file.

Required
integer id

The user ID

Required
object links

URLs to retrieve user information

Required
string self

The link to use to retrieve the user information

Required
string mention_name

User's @mention name

Required
string name

The display user name

Required
string version

An etag-like random version string.

Required
string oauth_client_id

The oauth client id that registered this webhook, if applicable.

integer webhook_id

The unique identifier for this webhook registration.

Required

room_message

Webhook for a normal room message

The event is sent as an HTTP POST with a JSON-encoded body containing:

Type Property Description Required?
string event

The webhook event name.

Required
object item

The event data.

Required
object message

The message sent.

Required
string date

The date the message was sent in ISO-8601 format.

Required
object file

The file URL attached to the message, if specified.

string name

The name of the file

Required
integer size

The size of the file in bytes

Required
string thumb_url

The URL of the thumbnail if it exists

string url

The URL of the file

Required
obj | str from

The user that sent the message.

May be null.

Required
object [from, object 1]

An object with the following properties.

Required
integer id

The user ID

Required
object links

URLs to retrieve user information

Required
string self

The link to use to retrieve the user information

Required
string mention_name

User's @mention name

Required
string name

The display user name

Required
string version

An etag-like random version string.

Required
string id

The internal unique id of the message

Required
array mentions

A list of mentioned users in this message.

An array of the following objects.

integer id

The user ID

Required
object links

URLs to retrieve user information

Required
string self

The link to use to retrieve the user information

Required
string mention_name

User's @mention name

Required
string name

The display user name

Required
string version

An etag-like random version string.

Required
string message

The message sent

Required
array message_links

A list of links extracted from the message and some extended data (currently only extracts the last link from the message)

An array of the following objects.

object image

Extended information extracted from an image link

string image

The URL of the image

string name

A name for the image

object link

Extended information extracted from a link to any other type of web page

string description

A longer description for the link

string faviconUrl

The URL of the favicon for this link

string fullUrl

The full URL for this link if the original was from a link shortener

string headerText

A descriptive header for the link

string linkText

An alternate description for this link

string title

The title for this link

object twitter_status

Extended information extracted from a twitter status update link

string created

The date of the post in UTC, formatted in ISO-8601

string name

The name of the Twitter user who posted the update

string profileImageUrl

The profile image of the user who posted the update

string screenName

The Twitter mention name of the user who posted the update (without the @).

string source

What application was used to post this tweet

string text

The text of the status update

Required
object twitter_user

Extended information extracted from a twitter profile link

integer followers

The number of followers for this Twitter user

Required
string name

The name of this Twitter user

Required
string profileImageUrl

The URL of this user's Twitter profile image

Required
string screenName

The Twitter mention name (without the @)

Required
string type

The type of link extracted which will determine the link metadata attributes.

Valid values: image, video, link, twitter_status, twitter_user.

Required
string url

The URL of the link that was extracted from the message

Required
object video

Extended information extracted from a video link

string author

The author of the video

string thumbnailUrl

A URL to a thumbnail of the video

string title

The title of the video

integer views

The number of views of this video

string type

The type of message being returned

Valid values: message, guest_access, topic, notification.

Required
object room

The room the message was sent to.

Required
integer id

ID of the room.

Required
boolean is_archived

Whether or not this room is archived.

Required
object links

URLs to retrieve room information

Required
string members

The URL to use to retrieve members for this room. Only available for private rooms. Note this link will be made available to public room from Dec 1, 2016

string participants

The URL to use to retrieve participants for this room

Required
string self

The URL to use to retrieve the full room information

Required
string webhooks

The URL to use to retrieve webhooks registered for this room

Required
string name

Name of the room.

Required
string privacy

Privacy setting

Valid values: public, private.

Required
string version

An etag-like random version string.

Required
string oauth_client_id

The oauth client id that registered this webhook, if applicable.

integer webhook_id

The unique identifier for this webhook registration.

Required

room_notification

Webhook for a room notification

The event is sent as an HTTP POST with a JSON-encoded body containing:

Type Property Description Required?
string event

The webhook event name.

Required
object item

The event data.

Required
object message

The message sent.

Required
string color

Background color for message.

Valid values: yellow, green, red, purple, gray.

Defaults to 'yellow'.

string date

The date the message was sent in ISO-8601 format.

Required
string from

The integration name that sent the message.

May be null.

Required
string id

The internal unique id of the message

Required
array mentions

A list of mentioned users in this message.

An array of the following objects.

Required
integer id

The user ID

Required
object links

URLs to retrieve user information

Required
string self

The link to use to retrieve the user information

Required
string mention_name

User's @mention name

Required
string name

The display user name

Required
string version

An etag-like random version string.

Required
string message

The message sent

Required
string message_format

Determines how the message is treated by our server and rendered inside HipChat applications.

Valid values: html, text.

Defaults to 'html'.

Required
string type

The type of message

Valid values: message, guest_access, topic, notification.

Required
object room

The room the message was sent to.

Required
integer id

ID of the room.

Required
boolean is_archived

Whether or not this room is archived.

Required
object links

URLs to retrieve room information

Required
string members

The URL to use to retrieve members for this room. Only available for private rooms. Note this link will be made available to public room from Dec 1, 2016

string participants

The URL to use to retrieve participants for this room

Required
string self

The URL to use to retrieve the full room information

Required
string webhooks

The URL to use to retrieve webhooks registered for this room

Required
string name

Name of the room.

Required
string privacy

Privacy setting

Valid values: public, private.

Required
string version

An etag-like random version string.

Required
string oauth_client_id

The oauth client id that registered this webhook, if applicable.

integer webhook_id

The unique identifier for this webhook registration.

Required

room_topic_change

Webhook for a room topic change

The event is sent as an HTTP POST with a JSON-encoded body containing:

Type Property Description Required?
string event

The webhook event name.

Required
object item

The event data.

Required
object room

The room who's topic has changed.

Required
integer id

ID of the room.

Required
boolean is_archived

Whether or not this room is archived.

Required
object links

URLs to retrieve room information

Required
string members

The URL to use to retrieve members for this room. Only available for private rooms. Note this link will be made available to public room from Dec 1, 2016

string participants

The URL to use to retrieve participants for this room

Required
string self

The URL to use to retrieve the full room information

Required
string webhooks

The URL to use to retrieve webhooks registered for this room

Required
string name

Name of the room.

Required
string privacy

Privacy setting

Valid values: public, private.

Required
string version

An etag-like random version string.

Required
obj | obj | str sender

The member that changed the topic.

Required
object [sender, object 1]

An object with the following properties.

Required
integer id

The user ID

Required
object links

URLs to retrieve user information

Required
string self

The link to use to retrieve the user information

Required
string mention_name

User's @mention name

Required
string name

The display user name

Required
string version

An etag-like random version string.

Required
object [sender, object 2]

An object with the following properties.

Required
array allowed_scopes

List of possible scopes that are allowed for requested tokens

string id

ID of the client.

Required
object links

URLs to retrieve oauth client information

Required
string self

The URL to use to retrieve the full oauth client information

Required
string name

The name of the client, if any

object room

The room, if specified, that this client is restricted to.

May be null.

Required
integer id

ID of the room.

Required
boolean is_archived

Whether or not this room is archived.

Required
object links

URLs to retrieve room information

Required
string members

The URL to use to retrieve members for this room. Only available for private rooms. Note this link will be made available to public room from Dec 1, 2016

string participants

The URL to use to retrieve participants for this room

Required
string self

The URL to use to retrieve the full room information

Required
string webhooks

The URL to use to retrieve webhooks registered for this room

Required
string name

Name of the room.

Required
string privacy

Privacy setting

Valid values: public, private.

Required
string version

An etag-like random version string.

Required
string topic

The new topic.

Required
string oauth_client_id

The oauth client id that registered this webhook, if applicable.

integer webhook_id

The unique identifier for this webhook registration.

Required

room_unarchived

Webhook for a room unarchival

The event is sent as an HTTP POST with a JSON-encoded body containing:

Type Property Description Required?
string event

The webhook event name.

Required
object item

The event data.

Required
object room

The room that was unarchived.

Required
integer id

ID of the room.

Required
boolean is_archived

Whether or not this room is archived.

Required
object links

URLs to retrieve room information

Required
string members

The URL to use to retrieve members for this room. Only available for private rooms. Note this link will be made available to public room from Dec 1, 2016

string participants

The URL to use to retrieve participants for this room

Required
string self

The URL to use to retrieve the full room information

Required
string webhooks

The URL to use to retrieve webhooks registered for this room

Required
string name

Name of the room.

Required
string privacy

Privacy setting

Valid values: public, private.

Required
string version

An etag-like random version string.

Required
obj | obj | str sender

The member that unarchived the room.

Required
object [sender, object 1]

An object with the following properties.

Required
integer id

The user ID

Required
object links

URLs to retrieve user information

Required
string self

The link to use to retrieve the user information

Required
string mention_name

User's @mention name

Required
string name

The display user name

Required
string version

An etag-like random version string.

Required
object [sender, object 2]

An object with the following properties.

Required
array allowed_scopes

List of possible scopes that are allowed for requested tokens

string id

ID of the client.

Required
object links

URLs to retrieve oauth client information

Required
string self

The URL to use to retrieve the full oauth client information

Required
string name

The name of the client, if any

object room

The room, if specified, that this client is restricted to.

May be null.

Required
integer id

ID of the room.

Required
boolean is_archived

Whether or not this room is archived.

Required
object links

URLs to retrieve room information

Required
string members

The URL to use to retrieve members for this room. Only available for private rooms. Note this link will be made available to public room from Dec 1, 2016

string participants

The URL to use to retrieve participants for this room

Required
string self

The URL to use to retrieve the full room information

Required
string webhooks

The URL to use to retrieve webhooks registered for this room

Required
string name

Name of the room.

Required
string privacy

Privacy setting

Valid values: public, private.

Required
string version

An etag-like random version string.

Required
string oauth_client_id

The oauth client id that registered this webhook, if applicable.

integer webhook_id

The unique identifier for this webhook registration.

Required