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 webhook user's API Key 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.
Not all requests from all webhooks will have a body (GETs, DELETEs), so ensure that this scenario is accounted for in any verification code. Depending on language, this may be an empty string or null. Consult your language's documentation for details.
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 can be trusted.
<?php
header('content-type: application/json');
$content = file_get_contents('php://input');
$yourWebhookAPIKey = '***************************';
$yourHash = base64_encode(hash_hmac('sha256', $_SERVER['HTTP_X_METALOCATOR_WEBHOOK_SIGNATURE_TIMESTAMP'] + $content, $yourWebhookKey));
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!");
}