Skip to main content
All CollectionsLeads
Webhook Security
Webhook Security

Use authentication to securely integrate with destination systems and signing secrets to verify the integrity of requests.

Michael Fatica avatar
Written by Michael Fatica
Updated over a week ago

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 signature

  • X-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!");
}

Did this answer your question?