Webhooks are HTTP calls to your server that make it really easy for you to receive events from your Nolt board. For example, you can be notified whenever users make new suggestions or comment on a post. Webhooks can be used to update an issue tracker, trigger custom alerts, or update a backup mirror. You're only limited by your imagination.
Your webhook should be hosted on a public HTTP server that accepts GET and POST requests. When you receive a webhook event, you should always respond with a "200 OK" in 5 seconds or less. If your webhook fails to meet either of the requirements, we will inform the board owner via email. If your webhook continues to fail, we may disable your webhook. Once the issue is fixed, you can enable the webhook again.
All webhooks have following body structure:
{
"event": "{{event name}}",
"boardId" : "{{board ID}}",
"triggeredAt" : "{{ISO 8601 timestamp}}",
"data" : {
"{{event type specific data}}"
}
}
Navigate to your board → Settings → Integrations → Webhooks. Fill out the form and click on Test and activate.
There are a couple of tools that make working with webhooks during development much more comfortable. One of them is ngrok, a tool that creates a tunnel from the public internet to a port on your local machine.
Anytime you try to enable a webhook in your board settings we'll send a GET request to your endpoint URL. This is required to ensure your webhook is authentic and working. Verification requests will look something like this:
GET /webhooks
?hub.mode=subscribe
&hub.challenge=55c4e474
&hub.verify_token=my-secret-verify-token
Host: yourwebsite.com
Whenever your endpoint receives such a request, it must respond with the hub.challenge. In addition to that, you can use the hub.verify_token field to verify Nolt sent the request.
// The string you set in the "Verify token" field
// when you configured your webhook on Nolt
const MY_VERIFY_TOKEN = 'my-secret-verify-token';
// Handle GET request to yourwebsite.com/webhooks
server.get('/webhooks', (req, res) => {
// Parse the query params
const mode = req.query['hub.mode'];
const token = req.query['hub.verify_token'];
const challenge = req.query['hub.challenge'];
// Checks if the mode and the verify token are correct
if (mode === 'subscribe' && token === MY_VERIFY_TOKEN) {
// Respond with the challenge value that
// was provided via the query param
res.status(200).send(challenge);
} else {
// Respond with '403 Forbidden' if verify tokens do not match
// to make sure that only Nolt can trigger your endpoint
res.sendStatus(403);
}
});
Once you click Test and activate in your Nolt webhooks settings, we'll send your endpoint a verification request which you must validate (see the previous step).
Whenever things happen in your board, we will send your endpoint a POST request with a JSON payload describing the change. Event notifications will look something like this:
POST /webhooks HTTP/1.1
Host: yourwebsite.com
X-Hub-Signature: sha256={{the generated SHA256 signature}}
Content-Type: application/json
{
"event": "comment.created",
"boardId": "9ccecc0d-98e2-4acf-bbc7-beae94deb9d2",
"triggeredAt": "2019-01-14T15:49:24.019Z",
"data": {
"comment": {
"id": "68a2e0ef-0355-46e1-aaf6-a7b07ed27dff",
"text": "The quick brown fox jumps over the lazy dog",
"type": "BASIC",
"post": {
"id": "bd6fcf91-2a4a-46c4-a085-611320ec8552"
},
"user": {
"id": "8ec38040-5cea-4f1a-87df-2e676096ddb3",
"name": "John Doe"
}
}
}
}
If a Signing secret was provided when you configured the webhook in your board, Nolt signs the notification payload using that secret and includes the signature in the request's X-Hub-Signature header, preceded with sha256=. This allows you to validate that the events were sent by Nolt, not by a third party. We strongly recommend you verify the signature to confirm that the notification is genuine.
// The string you set in the "Signing secret" field
// when you configured your webhook on Nolt
const MY_SIGNING_SECRET = 'my-signature-secret';
// Handle POST request to yourwebsite.com/webhooks
server.post('/webhooks', (req, res) => {
// Parse the POST params
const event = req.body.event;
const boardId = req.body.boardId;
const data = req.body.data;
// Parse the X-Hub-Signature header
const hubSignature = req.headers['x-hub-signature'];
// Compute an HMAC with the SHA256 hash function. Use the
// endpoint’s signing secret as the key, and use the raw
// request body string as the message.
const signature = createSha256Signature(
MY_SIGNING_SECRET,
req.rawBody
);
// Check if the signature is correct
if (hubSignature !== signature) {
// Respond with '403 Forbidden' if signatures do not match
return res.sendStatus(403);
}
// Your event notification handlers
if (event === 'comment.created') {
// Do something fancy here...
console.log(event, boardId, data);
}
// Returns a '200 OK' response to all requests
return response.sendStatus(200);
});
Do you need any other event notification sent from your Nolt board? Please submit your suggestion along with your use case here: https://feedback.nolt.io.