Webhook Integration

What are Webhooks?

The webhooks integration allows you to be automatically notified when something happens in LogMeOnce and notifies your application. Webhooks are one way that LogMeOnce can send automated messages or information to other apps. When a user is registered under your LogMeOnce account, your app can receive this event in Microsoft Teams, Slack or other apps supporting webhooks.

LogMeOnce provided event base integration and notifies your application when registered events are triggered.

How to Configure Webhooks

Step 1

Login to your LogMeOnce account and navigate to your Administrator Dashboard, Select Settings Menu and Select Developer. In the Webhook page, you will see a list of all your created Webhooks.

Status: Shows the current status of webhook integration.

URL: Shows the end-point URL of webhook integration.

Error Rate: Shows if there are any error with webhook integration.

More: Shows action menu to manage webhook integration.

Step 2

Click Add New and select to configure webhook integration

Step 3

Select one of the pre configured Webhook integrations or select default the Webhook integration. The integration configuration would be different based on your selected integration. The below image shows a default Webhooks integration setting.

Endpoint URL: Enter the endpoint URL of the third-party application which you would like to send messages.

Description: Enter an description for this integration.

Data Format: Select your application Data format. Support formats are JSON or Text. 

Events to listen: Select your desired events, as default all events are selected. 

Click on Add Webhook

Debugging Webhooks

To debug webhook integration, click on More and from menu select Show Logs

The webhook event log shows the details of the events.

The webhook event log shows the details of the events that were sent to your endpoint. In details section you can see:

• Response - your endpoint HTTP response code and response body
• Request - HTTP payload that was sent to your endpoint

Secure your webhook

Verify requests sent to your webhook endpoints. LogMeOnce signs all requests with the Lmo-Signature header.

Preventing replay attacks

A replay attack is when the attacker intercepts a request with valid payload and signature, then re-transmits them at a later time. To prevent such attacks LogMeOnce sends a timestamp with the Lmo-Timestamp header. Timestamp is also used in the signature, thus attackers can’t modify timestamp without invalidating the signature. Your server should use Network Time Protocol (NTP) to ensure server clock is accurate, but in case of time difference, you can allow certain tolerance to be acceptable. We suggest using 5 minutes tolerance for verifying timestamp.

Verifying signature manually

Signature is generated using hash-based message authentication code (HMAC) with SHA-256. Each webhook has its own unique signing secret that should be used to verify signatures. Both timestamp is saved and signature is generated at the time of sending the request to the endpoint. If the event request fails and is processed by retry logic in future new timestamp and new signature will be generated.

Step 1. Retrieve LMO_SIGNATURE and LMO_TIMESTAMP HTTP headers

Step 2. Prepare data to be signed
Data that is signed is created by concatenating:

• The timestamp (as string)
• Dot character: → . ←
• Raw payload JSON or Text

Step 3. Compute an HMAC with SHA256, and use signing secret as key

Step 4. Compare calculated signature with the signature from HTTP header

Step 5. Compare current timestamp with the timestamp from HTTP header
We recommend allowing timestamp differences within tolerance of 5 minutes.

The following PHP sample code is for verifying the signature.

<?php
DEFINE( "LOGMEONCE_WEBHOOK_SECRET", "<signing-secret-here>");

try {
if (!isset($_SERVER["HTTP_LMO_SIGNATURE"]))
throw new Exception("No signature");

if (!isset($_SERVER["HTTP_LMO_TIMESTAMP"]))
throw new Exception("No timestamp");

$timestampTolerance = 300; //5 min
$timestamp = $_SERVER["HTTP_LMO_TIMESTAMP"];
$payload = file_get_contents("php://input");
$signature = hash_hmac("sha256", "$timestamp.$payload", LOGMEONCE_WEBHOOK_SECRET);

if ($_SERVER["HTTP_LMO_SIGNATURE"] != $signature)
throw new Exception("Invalid signature or payload.");

if ($timestampTolerance > 0 && abs(time() - $timestamp) > $timestampTolerance)
throw new Exception("Invalid timestamp or not in tolerance.");

//TODO: continue with payload

http_response_code(200);
} catch(Exception $e) {
echo $e->getMessage();
http_response_code(400);
exit;
}
?>

This is an optional step to provide a better security.

Retry logic

If event request failed and HTTP response is not successful from your endpoint, we will retry:

• In 10 minutes, and if still fails we will retry:
• In 1 hour, and if still fails we will retry:
• In 1 day

After the above retries no more attempts will be made.

Deactivate logic

If your webhook is misconfigured or your endpoints no longer respond with 2xx successful HTTP response code it will be scheduled for deactivation. At the time of failed response, if there is no successful response within the last 3 days webhook is marked for deactivation which will be processed after another 3 days. Within this pending period if any successful request occurs pending deactivation is removed from your webhook.