Webhooks

Webhooks allow you to build or set up integrations which subscribe to certain events on Starmind. When one of those events is triggered, we’ll send a HTTP POST payload to the configured webhook URL. Webhooks can be used to implement custom notification mechanisms hooking into your existing chat clients or building mobile push services. You’re only limited by your imagination.

Configuration

Webhooks have to be enabled and configured before they can be used

Setting Description
web_hook_enabled Enables webhooks
web_hook_url Url which handles the payload
web_hook_events Comma separated list of supported webhook events
web_hook_secret (optional) A secret key to sign the payload

Events

When configuring webhooks for Starmind, you can choose which events you would like to receive payloads for. Subscribing to the specific events you plan on handling is useful for limiting the number of HTTP requests to your server. You can change the list of subscribed events by editing the corresponding network setting.

Each event corresponds to a certain set of actions that happen within your network. For example, if you subscribe to the notifications event you’ll receive detailed payloads every time notification is created.

The available events are:

Event name Description
notifications Any time a new notification is created

Payload

Each event type has a specific payload format with the relevant event information.

In addition to the fields documented for each event, webhook payloads include the user who performed the event (sender) as well as the user who is targeted by the event (receiver). Both fields are optional and depend on the event type and specific event.

Bear in mind that the payload for notification events like new_solution_to_your_question or new_comment_to_your_question allows question posers to be identified. In order to preserve question poser anonymity, this information must not be leaked to any end-users (except for the question poser himself).

Delivery headers

HTTP requests made to your webhook’s configured URL endpoint will contain several special headers:

Header Description
X-Starmind-Event Name of the event that triggered this delivery.
X-Starmind-Signature HMAC hex digest of the payload, using the hook’s secret as the key (if configured).
See here how to validate the payload.

Also, the User-Agent for the requests will have the prefix Starmind-Brainshot/Version.