Overview

To deploy MetaRouter's Analytics.js (AJS) tracking library or Standalone Sync Injector on your website, the tracking file must be hosted somewhere your website can load it. MetaRouter gives you two ways to do this:

Both methods support first-party hosting, which improves tracking efficacy in environments where ad blockers are in use.

Note for existing customers: The MetaRouter-hosted CDN option has been deprecated. MetaRouter no longer maintains a CDN on behalf of customers, and all customers are now required to host their own tracking files.

If you do not have access to the Auto-Deploy to Cluster option and would like to learn more about it, please contact your MetaRouter Customer Success Manager.

Key Concepts

Before getting started, it helps to understand two URLs you'll work with throughout setup:

Cluster File Endpoint The URL where MetaRouter hosts your built tracking file on your cluster. This is the source of truth for your file — your CDN origin or CI/CD job should pull from here.

https://YOUR_CLUSTER_URL/v1/pipelines/YOUR_WRITEKEY/file

Distribution URL The URL that visitors' browsers use to load the tracking file. This is the URL you enter in the MetaRouter File Builder, and it should point to wherever you are serving the file from (your CDN or your own infrastructure).

These two URLs serve different purposes: the Cluster File Endpoint is for retrieving the file during deployment; the Distribution URL is for serving the file to end users.

Auto-Deploy to Cluster

With auto-deploy, MetaRouter hosts your built tracking file at the Cluster File Endpoint as soon as you upload it. From there, you integrate with the endpoint using one of two approaches:

• CDN origin pull — Your CDN pulls from the cluster endpoint and serves the file to end users.
• CI/CD pipeline — An automated job pulls the file from the cluster endpoint, allowing you to test and approve it before deployment (in most cases, to a CDN).

Step 1 — Build and Upload Your File

1. In the MetaRouter UI, navigate to your web source and open the File Builder.
2. Configure your tracking file.
   1. Select your File location – choose Auto-deploy to Cluster.
   2. Enter your File Hosting URL (the URL browsers will use to load the file) and Ingestion Website URL (your Cluster's event ingestion endpoint).
   3. Configure file settings, consent settings, and Sync Injector Identity Syncs.
3. Click Save & Build File.
4. On the File Summary page, click Upload File to Cluster.

Your file is now available at the Cluster File Endpoint.

Step 2 — Integrate with the Cluster Endpoint

Option A: CDN Origin Pull

Point your CDN's origin at the Cluster File Endpoint. Your CDN will pull and cache the file, serving it to end users with minimal latency.

1. In your CDN, create a new distribution and set the Cluster File Endpoint as the origin.
2. Configure caching rules to suit your expected update frequency.
3. Confirm that HTTPS is enabled for your distribution.
4. Enter your CDN's domain as the Distribution URL in the MetaRouter File Builder.

Host header behavior: Some CDNs forward the client's Host header to the origin by default rather than the origin's hostname. If your CDN offers a setting to use the origin hostname as the Host header, enable it to ensure requests reach the cluster correctly.

When you update your file: Re-upload in the MetaRouter UI, then invalidate your CDN cache to ensure the latest version is served. Users with the file cached in their browser may need to clear their cache as well.

Option B: CI/CD Pipeline Integration

Pull the tracking file into your CI/CD workflow so you can test and approve changes before they reach production.

1. Configure a job in your CI/CD pipeline to fetch the file from the Cluster File Endpoint:

   https://YOUR_CLUSTER_URL/v1/pipelines/YOUR_WRITEKEY/file

2. Add any testing or approval steps required by your team.
3. Deploy the approved file to your server or CDN.
4. Ensure the Distribution URL in the File Builder matches where you are serving the file from.

Keeping the file up to date: Your pipeline job needs to be triggered each time you rebuild the file in MetaRouter. Consider using a webhook (below) to automate this.

Option C: Serve File Directly from Cluster (Not Recommended)

It is possible to set the Cluster File Endpoint as your Distribution URL, so client browsers fetch the tracking file directly from the cluster. This is not recommended for production use.

The MetaRouter cluster is not a CDN and is not optimized to serve static files at scale. Using this option in production will result in increased file load latency and added stress on cluster infrastructure, which can affect the reliability of your data pipeline.

This option may be useful for low-volume testing scenarios where a CDN or other file hosting strategy has not yet been configured.

Setup:

1. Set your File Hosting URL in the File Builder to the Cluster File Endpoint (available on the File Summary page): https://YOUR_CLUSTER_URL/v1/pipelines/YOUR_WRITEKEY/file
2. Build and upload your file as described in Step 1.

Using a different hosting strategy? Options A, B, and C represent common hosting approaches, but they are not exhaustive. If your team has a different hosting strategy in mind, that may work fine — just make sure to inform your Customer Success Manager so they can ensure your setup is fully supported.

Step 3 (Optional) – Configure Your Deployment Webhook

Webhook notifications let MetaRouter send real-time HTTP notifications to your server when key events occur in your account. This is the primary way to know when a new tracking file is ready for review or has been deployed to a cluster.

When you configure a webhook, MetaRouter sends a signed POST request to your specified URL each time a subscribed event occurs. You can use these notifications to automate downstream processes — for example, pulling the latest tracking file from the CDN, triggering QA pipelines, or alerting your team.

Each organization supports one webhook endpoint.

Event Types

You may subscribe to one or both event types when creating or updating your webhook.

Setup

Step 1 — Navigate to Webhook Settings

In the MetaRouter dashboard, go to Settings → Webhooks.

Step 2 — Create a Webhook

Click Create Webhook and provide:

• Endpoint URL — The HTTPS URL where MetaRouter will send notifications.
• Event Types — Select one or both: file.config_saved, file.deployed.
• Enabled — Whether to start receiving notifications immediately (default: yes).

URL requirements:

• Must use https://
• Must use a hostname (not a bare IP address)
• Must not include credentials (e.g., https://user:pass@... is not allowed)
• Must resolve to a publicly routable IP address

Step 3 — Save Your Signing Secret

After creation, MetaRouter displays a signing secret once. Copy it immediately — it cannot be retrieved again. You will use this secret to verify the authenticity of incoming webhook requests. If you lose your signing secret, contact MetaRouter support — self-service webhook deletion is not available.

Managing Your Webhook

From Settings → Webhooks you can:

• Enable or disable the webhook without deleting it.
• Update the endpoint URL — MetaRouter will re-validate the new URL before saving.
• Update event subscriptions — Add or remove event types at any time.

Disabling the webhook stops all deliveries. Re-enabling resumes them for future events.

Request Format

MetaRouter sends an HTTP POST to your endpoint with the following headers:

Payload Structure

{
  "event_type": "file.deployed",
  "timestamp": "2026-03-18T10:30:00Z",
  "data": {
    "analytics_file_id": "a1b2c3d4-...",
    "org_id": "your-org-id",
    "org_name": "Acme Corp",
    "pipeline_id": "e5f6g7h8-...",
    "pipeline_name": "My Pipeline",
    "writekey": "wk-abc123",
    "cluster_id": "i9j0k1l2-...",
    "cluster_name": "US East",
    "source_url": "https://your-cluster.mr.example.com/v1/pipelines/wk-abc123/file",
    "cdn_url": "https://cdn.metarouter.io/wk-abc123/analytics.js",
    "file_hosting_type": "mr_hosted",
    "user_email": "[email protected]"
  }
}

Payload Fields

source_url and cdn_url are only present on file.deployed payloads. They are not included in file.config_saved events. Note that source_url points to the cluster directly (not a CDN).

Verifying Signatures

All requests from MetaRouter are signed using HMAC-SHA256 with the signing secret generated at webhook creation. Always verify this signature before processing a webhook.

Algorithm

1. Read the X-MetaRouter-Timestamp header value (a Unix timestamp in seconds).
2. Construct the signed message: <timestamp>.<raw_request_body>
3. Compute HMAC-SHA256 using your signing secret as the key and the message as the input.
4. Hex-encode the result.
5. Compare to the value in the X-MetaRouter-Signature header (format: sha256=<hex>).

Important: The raw_request_body must be the exact bytes received in the HTTP request — do not parse and re-serialize the JSON. MetaRouter sends compact JSON with no extra whitespace or newlines. Re-formatting the body (e.g., pretty-printing) will produce a different signature.

Example — Node.js

const crypto = require('crypto');

// body must be the raw request body string — do not JSON.parse() and re-stringify
function verifySignature(secret, timestamp, body, signatureHeader) {
  const message = `${timestamp}.${body}`;
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(message)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}

Example — Python

import hmac
import hashlib

# body must be the raw request body string — do not json.loads() and re-dump
def verify_signature(secret: str, timestamp: str, body: str, signature_header: str) -> bool:
    message = f"{timestamp}.{body}"
    expected = "sha256=" + hmac.new(
        secret.encode(),
        message.encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

Use a constant-time comparison (e.g., timingSafeEqual / hmac.compare_digest) to prevent timing attacks.

Replay protection: Consider rejecting requests where X-MetaRouter-Timestamp is more than 5 minutes old.

Responding to Webhooks

Your endpoint should:

• Return a 2xx HTTP status code to acknowledge receipt.
• Respond within 10 seconds — requests that time out are treated as failures.
• Process the event asynchronously if your logic may take longer than 10 seconds; respond 200 OK immediately and handle it in the background.

Retries

If your endpoint does not return a 2xx response or times out, MetaRouter will retry the delivery:

• Retry interval: 30 seconds
• Maximum retries: 2 additional attempts (3 total)

If your endpoint fails repeatedly, the webhook will be temporarily paused (circuit breaker) for 5 minutes before attempting delivery again.

Delivery Logs

MetaRouter logs every webhook delivery attempt, including:

• The event type and full request payload sent
• The HTTP response status code and response body (up to 8 KB)
• Delivery duration in milliseconds
• Success or error details

Delivery logs are available in the MetaRouter dashboard under Settings → Webhooks → Delivery History.

Permissions

The following role permissions are required to manage webhooks:

Roles with access: Admin, Deployment Manager, Integration Manager.

Webhook Configuration Frequently Asked Questions

Can I have more than one webhook endpoint? No. Each organization is limited to one webhook endpoint. You can update the URL or event subscriptions at any time.

What happens if I lose my signing secret? The secret is shown only once at creation time. If you lose it, contact MetaRouter support to have your webhook reset. Self-service deletion of webhooks is not available.

Can I test my webhook without a real event? Not directly from the dashboard at this time. You can temporarily point the webhook to a tool like Webhook.site or a local tunnel (e.g., ngrok) to inspect live payloads.

What IP addresses does MetaRouter send webhooks from? Contact MetaRouter support for the current list of egress IP addresses if you need to allowlist them in your firewall.

Why isn't my webhook receiving events?

• Confirm the webhook is enabled in Settings → Webhooks.
• Check Delivery History for failed attempts and error messages.
• Ensure your endpoint is publicly accessible over HTTPS.
• Verify your endpoint responds within 10 seconds.

Manual Deployment

Manual deployment gives your team full control over the file before it is deployed. No file is hosted on the cluster — instead, you download the file from MetaRouter and manage hosting entirely within your own infrastructure.

Best for: Organizations that require review and approval of any JavaScript file before it reaches their website.

Steps

1. In the MetaRouter UI, navigate to your web source and open the File Builder.
2. Configure your tracking file and click Save & Build File.
3. On the File Summary page, download the built file.
4. Host the file on your server or CDN.
5. Ensure the File Hosting URL in the File Builder matches the URL where you are hosting the file.

Each time you make changes to your tracking file configuration, you will need to repeat this process to download and redeploy the updated file.

Reference