Wiki

Webhooks can be registered by an add-on to receive a notification of an event.

For details on the webhooks that HipChat exposes, please see the HipChat webhook documentation.

Listening to add-on events

Any webhooks defined through the builder interface, as well as the automatically configured install and uninstall webhooks, generate events on the addon object. To listen to webhook events with Koa-style generator functions, you can use the following API:

addon.onWebhook('install', function *() {
  // use the koa context (this) to access request, response, tenant info, and tenant services normally
});

Defining webhooks dynamically

Sometimes, you won't know what webhooks you want to define at the time that the descriptor is defined or built. This may happen if your add-on creates webhooks in response to add-on configuration, for example. In this case, you can add or remove webhooks dynamically using the tenantWebhooks service API available on any Koa add-on context.

this.tenantWebhooks.add('room_message', /^\/hello/i);

To handle this event, simply define a webhook listener on the addon:

addon.onWebhook('room_message', function *() {
  // handle the webhook, dispatching to an appropriate subroutine based on data in the query string and webhook body
});

REST Client

For a comprehensive breakdown of the HipChat operations available to ac-koa, please read the REST Client documentation.

The ctx.tenantWebhooks interface is high-level API for adding or removing webhooks for a given tenant, in such a way that this library can manage any required routing, authentication, and dispatching necessary to provide a similar level of service as is enjoyed by statically defined webhooks (i.e. those defined as part of the capabilities descriptor when the add-on is defined at server startup).

See the Hearsay example add-on for a functioning example of the webhook manager API.

Method	Description
`get(name)`	Retrieve a webhook by it's name. Available only when operating within a room context.
`get(roomId, name)`	Retrieve a webhook by room id and webhook name.
`add(event)`	Add a new webhook by specifying the webhook event type. Available only when operating within a room context.
`add('room_message', pattern)`	Add a new webhook by specifying the webhook event type and a regular expression to match.
`add(definition)`	Add a new webhook by specifying a webhook object of the form: `{event: event, pattern: pattern}`. Available only when operating within a room context.
`add(roomId, event)`	Add a new webhook by specifying the room id and webhook event type.
`add(roomId, 'room_message', pattern)`	Add a new webhook by specifying the room id, webhook event type and a regular expression to match.
`add(roomId, definition)`	Add a new webhook by specifying the room id and a webhook object of the form: `{event: event, pattern: pattern}`.
`remove(name)`	Remove a webhook by it's name. Available only when operating within a room context.
`remove(roomId, name)`	Remove a webhook by it's room id and name.

Webhook data extraction and normalization

Webhook listeners added via either addon.webhook(...) (for webhooks defined using the add-on builder API convenience method) or addon.onWebhook(...) (for dynamic or non-builder based webhook listeners) are provided with both raw and normalized views of the webhook body. Since not all webhooks organize their data the same way, extracted and normalized webhook fields are attached directly to the Koa context, along side the raw webhook object. Not all webhooks provide all fields and some of these fields are themselves complex objects, so consult the webhook documentation for information about what to expect when.

Field	Description
`ctx.webhook`	The raw webhook payload.
`ctx.webhookId`	The webhook id.
`ctx.room`	The relevant room model object.
`ctx.sender`	The relevant sender model object.
`ctx.message`	The message object, if any. Only in `room_notification` and `room_message` webhooks.
`ctx.content`	The message field of the message object, if any. Only in `room_notification` and `room_message` webhooks.
`ctx.topic`	The room topic, if any. Only in `room_topic_change` webhooks.
`ctx.match`	The result of running RegExp.exec() on `ctx.content`, if apporpiate. Only in `room_notification` webhooks, using the webhooks' registered `pattern`.