Configure Your Webhook URL

Configure Webhook Settings

Use the MetaMap Dashboard webhook settings to configure a URL and secret to receive webhooks from your users' verifications. Visit the Integration tab and select webhooks to configure one webhook URL and webhook secret for each metamap ID you want to integrate into your application.

📘

MetaMap uses a static IP to send webhooks

If your system uses IP filtering, make sure you can receive webhooks from all 4 of our IP addresses:

52.55.16.54 52.5.135.13 18.209.133.212 52.7.73.154

Webhook Secret

You need to establish a 'webhook secret,' which serves as a shared key. We'll use this secret to hash the webhook payload and send it as header x-signature in our requests. By applying the same process on your end and comparing the resulting string with the one received in the header, you can always ensure that the webhook is originating from MetaMap and not from any other source. This mechanism provides security and authentication for your webhook communication.

📘

Webhook Secret Requirements

Your webhook secret must:

• Have ≥16 characters
• Have ≥1 upper-case and ≥1 lower-case letter
• Have ≥1 digit [0-9]

You can also use the "Generate a strong secret" button.

The following example in JavaScript adds a decoding script.

    const crypto = require('crypto');
    
    // A sample webhook coming from MetaMap
    const WEBHOOK_PAYLOAD = 
    {   
        eventName: 'verification_completed',
        metadata: {email: '[email protected]'},
        resource: 'https://api.mati.io/api/v1/verifications/db8d24783',
    };
    
    const MERCHANT_SECRET = 'your_metamap_webhook_secret';
    
    // MetaMap hashes your webhook payload
    const signature = crypto.createHmac('sha256', MERCHANT_SECRET).update(JSON.stringify(WEBHOOK_PAYLOAD)).digest('hex');
    console.log(signature);
    
    function verify(signature, secret, payloadBody) {
        let hash = crypto.createHmac('sha256', secret);
        hash = hash.update(payloadBody).digest('hex');
        return crypto.timingSafeEqual(Buffer.from(hash), Buffer.from(signature));
    }    
    let isValidPayload;
    
    isValidPayload = verify(signature, MERCHANT_SECRET, JSON.stringify(WEBHOOK_PAYLOAD));
    console.log(isValidPayload);

For each verification that MetaMap processes, we will send you webhook events. Review our Webhook Specifications for more details on each event and how to access the Resource URL.