Webhooks provide an additional security measure to verify that the webhook is genuine and has come from MetaLocator. This can be useful if you're looking to ensure only MetaLocator webhooks are being made to your endpoint and ensure the information is genuine and as the system expects. These signatures will also help prevent against replay attacks.
Configuring Authentication
To configure webhooks for an interface, click Interfaces, select the desired Interface, click Lead Generation and scroll down to the settings shown below:
Provide your HTTPS URL in the Lead Webhook URL setting and choose an Authentication Method.
Authentication of Webhook Requests
Webhook requests will contain two headers which can be used to verify the request's authenticity:
X-METALOCATOR-WEBHOOK-SIGNATURE- the main signatureX-METALOCATOR-WEBHOOK-SIGNATURE-TIMESTAMP- the timestamp used to verify the signature
This is used in conjunction with the payload of the request.
Verifying the signature
Sign the body and signature timestamp with the Shared Token using SHA256, then base64 encoding the resulting digest.
Represented simply: base64(HMACSHA256(TIMESTAMP + BODY))
To verify the signature, create the same SHA256 HMAC signature and then compare it to the webhook payload to ensure that they match. If they match, then you can be sure that the webhook came from MetaLocator. If they don't, it may be a request from another source and should not be trusted.
PHP Example
The below simple example shows the recipient script decoding the signature using the timestamp and API key. If the data validates, then the signature and payload can be trusted.
<?php
header('content-type: application/json');
$content = file_get_contents('php://input');
$yourWebhookSharedToken = '***************************';
$yourHash = base64_encode(hash_hmac('sha256', $_SERVER['HTTP_X_METALOCATOR_WEBHOOK_SIGNATURE_TIMESTAMP'] . $content, $yourWebhookSharedToken));
if ($yourHash === $_SERVER['HTTP_X_METALOCATOR_WEBHOOK_SIGNATURE']) {
$content = json_decode($content);
echo json_encode("Sample Response " . $content->lead->id);
}else{
die("Not a valid webhook!");
}