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

1624

Metamap Dashboard screenshot: Configure new Webhook and Webhook URL and secret

Webhook Secret

You have to set a "webhook secret" that we will use to hash out on of the headers in our webhooks, by decoding it using your "webhook secret" and comparing the decoded string you can always make sure that the webhook is coming from MetaMap and not another party.

📘

Webhook Secrets 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.