Webhooks

Webhooks can be registered by an add-on to receive a notification of events from HipChat. For a comprehensive list of events, see the webhooks section in the API reference.

Room_message Webhook

In particular, the room_message Webhook can be used by your integration to listen to messages in particular rooms, which is helpful for:

• Adding Slash commands, e.g. /build my-project
• Watching for links of a particular format

The receiver of a room_message Webhook may optionally return a JSON response (same format as the request message for send_room_notification), in which case it will be sent as a notification to the room, as a response to the original message.

Registering a Webhook

There are two ways an add-on can register a webhook: via the descriptor, or by invoking a REST endpoint:

Via the descriptor

You can subscribe to a list of webhooks by declaring them in the add-on descriptor: 

1
2
"capabilities": {
    ...,
    "webhook": [
        {
            "event": "room_message",
            "pattern": "^\\/hello$",
            "url": "youraddon.com/hello",
            "name": "Hello webhook",
            "authentication": "jwt"
        }
    ]
}

Via this method, you can register webhooks globally, or for specific rooms.

Via REST

Your add-on can manage webhooks via the REST API: 

• create_webhook
• get_all_webhooks
• delete_webhook

Note that this requires the admin_room scope.

This method can only be used in the context of a room (you cannot manage global webhooks this way).

Securing a Webhook

Whenever HipChat makes a REST call to your add-on for a webhook, it includes a JWT token in the "signed_request" HTTP query parameter.

You should verify this token.