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!");
}
Error Handling
The HTTP Response Code and HTTP Response Body will be stored along with the lead object. Your Webhook should respond with an appropriate HTTP status code indicating success, e.g. 200.
Error Reports
When a webhook failure is detected, MetaLocator will email the account owner an error report. Error reports are generated in the following scenarios:
HTTP response codes of 300 or greater will trigger an error report.
Unresponsive endpoints that timeout
Endpoints with an invalid SSL certificate
Unresolved DNS of the Webhook URL
Network connectivity issues.
Endpoints that fail to establish an HTTP connection will be stored with an "999" HTTP status code and any error messages will be stored in the Webhook Response field.
A sample Webhook error email can be found below:
