Matomo Server-Side: How It Works

🔍 Can you go server-side with Matomo? Yes — here’s how.

Matomo is not only a privacy-first analytics platform. It’s also server-side ready.
Thanks to its Tracking HTTP API, you can send hits without JavaScript, directly from your server, Python script, or a server-side tag manager.

✅ Common use cases

• 💬 Email open tracking (1×1 pixel image)
• 🛒 Purchase confirmed via backend call
• ⏱️ CRON job or server-triggered event
• 🧪 Feature toggles or A/B tests without JS
• 🔐 Full GDPR-compliant tracking (on-premise, no cookies)

🧩 Example of server-side HTTP request

GET https://matomo.mysite.com/matomo.php
  ?idsite=1
  &rec=1
  &url=https://mysite.com/thank-you
  &action_name=Order Confirmed
  &uid=123456
  &e_c=ecommerce
  &e_a=purchase
  &e_v=79.99

You can send this from any backend (PHP, Python, Node.js…), or even a server-side tag manager like GTM Server.

🔗 Reconciling client-side and server-side data

To make sure Matomo ties together what happens in the browser and what happens in your backend, you need a shared key.

👉 That key is uid (User ID).

🔧 What to do:

Client-side (JS or Tag Manager):

_paq.push(['setUserId', '123456']);

Server-side (HTTP request):

&uid=123456

🧠 Matomo will link all these actions under the same user profile, across sessions and channels.

⚠️ Without uid, your server-side hits will remain isolated and disconnected from frontend activity.

---

📌 Benefits of Matomo server-side tracking

• No JS dependency (great for strict browsers or blockers)
• No cookies if you don’t want them
• Fully customizable data flow
• Works in any backend or cloud stack
• Ideal for regulated industries, custom analytics, or data orchestration tools (like GTM Server, Airflow, Zapier, etc.)

---

🎯 In short

Matomo gives you a clean and powerful way to run server-side analytics — without relying on external scripts, and with full user data reconciliation via uid.

🧩 Python example: Sending a server-side hit to Matomo

import requests

MATOMO_URL = 'https://matomo.mysite.com/matomo.php'
SITE_ID = 1
USER_ID = '123456'  # Same UID as set client-side
EVENT_NAME = 'Server-side Order Confirmed'
EVENT_CATEGORY = 'ecommerce'
EVENT_ACTION = 'purchase'
EVENT_VALUE = 79.99

payload = {
    'idsite': SITE_ID,
    'rec': 1,
    'uid': USER_ID,
    'action_name': EVENT_NAME,
    'e_c': EVENT_CATEGORY,
    'e_a': EVENT_ACTION,
    'e_v': EVENT_VALUE,
    'url': 'https://mysite.com/thank-you',
    'ua': 'Python-Server-Agent/1.0',
}

response = requests.get(MATOMO_URL, params=payload)

if response.status_code == 200:
    print("✅ Matomo hit sent successfully.")
else:
    print(f"❌ Failed to send hit: {response.status_code}")

📌 Python example: how to send server-side data to Matomo

Here’s a basic Python script that sends an ecommerce purchase event directly to Matomo via the HTTP API.

The key things to note:

• It uses the uid field to tie the event to an identified user (reconciliation).
• It includes typical event parameters: category, action, value.
• It passes a url even if it’s not loaded in a browser — Matomo uses this for reporting context.

This can be part of a:

• server-side confirmation flow (e.g. after payment)
• backend event dispatcher
• Python microservice
• ETL job sending historical or batch data

✅ If you already use _paq.push(['setUserId', '123456']) on the frontend, this hit will be merged under the same user in Matomo.

🧪 You can test the call in real time using Matomo’s “Real-time” dashboard.