Sorry, we don't support your browser.  Install a modern browser

Webhooks

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.

Requirements

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.

Webhook content

All webhooks have following body structure:

{
  "event": "{{event name}}",
  "boardId" : "{{board ID}}",
  "triggeredAt" : "{{ISO 8601 timestamp}}",
  "data" : {
    "{{event type specific data}}"
  }
}

1. Add your webhook endpoint to Nolt

Navigate to Manage boardIntegrationsWebhooks. Fill out the form and Click on Save configuration.

  • Endpoint URL
    Enter a URL that we should send the HTTP requests to.
  • Verify token (optional)
    Enter a random string in the field or click on Generate. This token will be sent with the verification request when you enable this integration. You can use it to validate the request came from this board. Remember, this token is secret. It should only be used from the server side of your application.
  • Signing secret (optional)
    Enter a random string in the field or click on Generate. This secret will be used to sign the request payload with a signature and include the signature in the request's X-Hub-Signature header. Remember, this token is secret. It should only be used from the server side of your application.

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.

2. Verify your webhook endpoint

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.

Show example
// 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);
  }
});

3. Enable the integration

Once you click Enable integration in your Nolt webhooks settings, we'll send your endpoint a verification request which you must validate (see the previous step).

4. Receive event notifications

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"
      }
    }
  }
}

Validating payloads

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);
});

Available webhook events

  • comment.created
  • comment.deleted
  • post.created
  • post.deleted
  • post.status.updated

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.