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.
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:
Via this method, you can register webhooks globally, or for specific rooms.
Your add-on can manage webhooks via the REST API:
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.