Overview

Webhooks let you register an URL that Qminder's servers will send a HTTP request to, anytime the following actions happen in your account:

• A location is added to the Qminder account (using the location_created event)
• A location's settings have changed (using the location_changed event)
• A line's settings have changed (using the line_changed event)
• A ticket is added to queue (using the ticket_created event)
• A ticket is called for service (using the ticket_called event)
• A ticket is re-called (using the ticket_recalled event)
• A ticket's data is changed (using the ticket_changed event)
• A ticket is marked as served (using the ticket_served event)

Registering an URL

In order to receive webhook events on your company's backend servers, the webhook's URL has to be registered in Qminder Dashboard.

After registration, events will be sent to the URL.

Here's how to register an URL:

1. Go to Qminder Dashboard
2. Log in as an Administrator or Owner of the account
3. Using the left side-bar, click on the bottom most option (your profile photo), and select "Organization Settings".
4. Select "Developer Tools" from the top navigation bar.
5. Click on the "New endpoint" button.
6. Enter the URL to be notified
7. Click on "Save" to finish registration.

After completing this procedure, events on the account will be sent to the URL.

The following rules apply for an URL:

• Begins with http(s)://
• Consists of at least domain and subdomain
• Maximum length is 512 characters

HTTP request example

As an example, if the URL "https://example.com/webhooks" has been registered in Qminder as a webhook listener, it will receive this POST request when a ticket is created:

POST /webhooks HTTP/1.1
X-Qminder-Signature: SIGNATURE
Content-Type: application/json

{
  "type": "ticket_created",
  "data": {
    "id": "7024061",
    "status": "NEW",
    "source": "MANUAL",
    "line": 12345,
    "firstName": "Jane",
    "lastName": "Eyre",
    "phoneNumber": 12125551234,
    "email": "[email protected]",
    "created": {
      "date": "2020-05-25T00:00:00Z"
    },
    "extra": [
      {
        "title": "Repeat visitor?",
        "value": "Yes"
      }
    ]
  }
}

Webhook authentication

It is possible to authenticate Qminder webhooks using a HMAC (hash-based message authentication code) signature. Qminder's servers will sign every webhook request and pass the HMAC to your backend servers.

Qminder uses the HMAC-SHA256 signature algorithm.

Here's how to authenticate Qminder webhooks:

1. After adding a webhook in Qminder Dashboard, copy the "Secret" value and give it to your software.
2. Every time a request is received, digest the URL and the POST request body with the secret value.
3. Extract the digest result in hexadecimal, and compare it with the request's X-Qminder-Signature header.

Here's how to do it in code:

// this example is in JavaScript, with Node.js
const crypto = require('crypto');
const QMINDER_SECRET = '71dX4IUKcJMDOaMHeA5IACBSHJkS4LzYNXlZPleg';
function getSignature(url, postBody) {
  const hmac = crypto.createHmac('sha256', QMINDER_SECRET);
  hmac.update(url);
  hmac.update(postBody);
  const signature = hmac.digest('hex');
  return signature;
}
console.log(
  getSignature(
    "https://example.com/webhooks",
    "{ \"statusCode\": 200 }"
  )
);