Web hooks

A Web hook is a way for us to notify your application or server that an event occurred. It allows bidirectional communication between UNLOQ and your application server, by creating an HTTP request to a URL, when a certain action occurs. You can look at it as a basic HTTP callback.

The logout webhook

When a user uses his device to login via push notifications, you can choose to send his session id to be stored on the user's device, so that the user can remotely logout and terminate said session. If a session id is sent via the /v1/token API call, a user can choose to terminate the session, sending a POST request to your application's logout webhook, containing their session id.

UNLOQ allows users to perform remote logout, when authenticating to your application via push notifications. A common security threat is when users leave their device unattended, or forget to manually logout of an application. We address this issue by enabling them to logout by the push of a button. The logout webhook should only be called by UNLOQ, so your regular users should not land on it.

The actual POST data the logout request will contain:

{
   "unloq_id": "", // The UnloqID from the user trying to logout
   "sid": ""   // The user's session ID, which you previously sent through the /v1/token AP call.
}

The account activate/deactivate hook

When a user finalizes the on-boarding process from one of your register widgets, finalizes the deactivation process or as a result of an API call from your server to deactivate or activate the device (for on-premise only), UNLOQ will trigger the account activate webhook with the following payload:

{
    "unloq_id": "", // The UnloqID from the user that activated his account
    "email": "",    // The e-mail used to activate the account
    "ip": ""        // The user's IP address, if available
  }

Verifying a webhook POST signature

All our direct web hooks towards your application come with a specific X-Unloq-Signature HTTP header, that signs the requests's POST data, using HMAC-SHA256, with your application's API Secret as the key. Although this is an optional step, we suggest you verify the integrity of the webhook's data.

Signature algorithm (Node.js implementation)

• Create a string with the full URL path (including leading slash and query string, excluding the hostname
• Sort the POST payload by key, alphabetically
• Append each {key,value} tuple from the sorted array to the string
• Create an HMAC-SHA256 signature with your application's API Secret as the secret
• Base64 encode the signature
• Verify the resulting signature with the one received in the HTTP Header

Terminating the webhook request

When calling a webhook, UNLOQ will set the HTTP request timeout to 3000 ms with a maximum response size of 100kb. If everything has gone well and you've successfully finalized processing the triggered event, just respond with a 200 OK status. We treat any other status code as a failure, and (should it be the case) warn the user about the failed attempt.

Have a question? You can always send us an email at support@unloq.io, or contact us on chat.

For security related concerns, please visit our Security page.