Skip to main content
🔔 Real-time Event NotificationsWebhooks allow Trackpilots to send real-time event data to your application whenever an event occurs.

​
📌 Overview

Webhooks enable your system to automatically receive event notifications from Trackpilots.
Whenever a selected event occurs, Trackpilots sends a POST request to your configured webhook URL with the event payload. You can create and manage webhooks from the Developer Tools section in the Trackpilots dashboard.

​
➕ Create a Webhook

Follow the steps below to create a new webhook:
  1. Open Developer Tools in your Trackpilots dashboard.
  2. Click Webhooks in the menu.
    👉 Direct link: https://app.trackpilots.com/developer-tools/webhooks
  3. Click the Create Webhook button in the top-right corner.
  4. Fill in the details:
    • 🏷️ Webhook Name – Friendly name for identification
    • 🌐 Webhook URL – The endpoint where events will be delivered 
      https://yourdomain.com/webhooks/trackpilots
  5. Select the events you want to receive.
  6. Click Create.
🎉 Your webhook is now active.

​
📡 Supported Events

​
🌍 All Events

  • Enable this option to receive all available Trackpilots events.

​
💻 Desktop Events

Currently supported desktop tracking events:
  • 📸 desktop.screenshot_tracking.captured
  • 🧠 desktop.app_tracking.captured
  • 🕒 desktop.activity_tracking.captured
Each event triggers a webhook call when captured.

​
⚙️ Webhook Delivery Behavior

  • Trackpilots sends a POST request to your webhook URL
  • Payload is delivered in JSON format
  • Your server must return HTTP 2xx to confirm successful delivery

​
🧑‍💻 Sample Webhook Receiver (Node.js + Express)

Below is a secure Express.js webhook receiver with HMAC signature verification. 
import express from "express";
import crypto from "crypto";

const app = express();

// Webhook endpoint
app.post(
  "/webhooks/trackpilots",
  express.raw({ type: "application/json", limit: "50mb" }),
  (req, res) => {
    try {
      console.log("✅ Webhook received successfully from Trackpilots...");

      // 🔐 Trackpilots webhook secret
      const webhookSecret = process.env.TRACKPILOTS_WEBHOOKS_SECRET_KEY;

      // Read headers
      const signature = req.headers["x-webhook-signature"];
      const timestamp = req.headers["x-webhook-timestamp"];

      if (!signature || !timestamp) {
        return res.status(400).send("Missing webhook signature headers");
      }

      // Raw body buffer
      const rawBody = req.body;

      // 🔏 Build payload for signing
      const payloadToSign = `${timestamp}.${rawBody.toString()}`;

      const expectedSignature = crypto
        .createHmac("sha256", webhookSecret)
        .update(payloadToSign)
        .digest("hex");

      // 🛑 Verify signature
      if (signature !== expectedSignature) {
        return res.status(401).send("Invalid webhook signature");
      }

      // ✅ Verified → Parse event
      const event = JSON.parse(rawBody.toString());
      console.log("🎯 Verified Trackpilots Event:", event);

      // Respond success
      res.status(200).send("Webhook processed successfully ✅");
    } catch (error) {
      console.error("❌ Webhook processing error:", error);
      return res.status(500).send("Webhook processing failed");
    }
  }
);

// Start server
app.listen(3000, () => {
  console.log("🚀 Webhook server running on http://localhost:3000");
});

​
🔐 Signature Verification Flow

Trackpilots secures webhooks using HMAC SHA256 signature validation to ensure authenticity and integrity.

​
📤 Trackpilots Sends

Each webhook request includes:
  • 🧾 x-webhook-signature
  • ⏱️ x-webhook-timestamp
  • 📦 Raw JSON request body

​
🧮 Your Server Generates

Your server must compute the expected signature:
HMAC_SHA256(timestamp + ”.” + body, WEBHOOK_SECRET)

​
✅ Signature Match Rule

If the computed signature matches the received signature: 👉 The webhook request is trusted and verified. This ensures the request is authentic and not tampered with.

​
🧪 Test Webhooks Locally

You can test Trackpilots webhooks in your local environment using ngrok.

​
🚀 Start ngrok

ngrok http 3000
This exposes your local webhook server to the internet.

​
🌐 Set Webhook URL in Trackpilots

Use the generated ngrok public URL:
https://YOUR_NGROK_URL/webhooks/trackpilots
Paste this URL into the Webhook URL field in the Trackpilots dashboard.

​
⚠️ Security Best Practices

⚠️ Ensure High AvailabilityMake sure your webhook endpoint is publicly accessible and highly available to avoid missed events.
  • Validate incoming webhook payloads.
  • Log webhook requests for debugging and auditing.
  • Handle duplicate events gracefully.
  • Secure your endpoint using signature validation (recommended).
🛡️ Always verify webhook signatures: Never trust incoming webhook requests without validation.

​
🔒 Recommended Practices

  • Store webhook secrets in environment variables
  • Reject requests with invalid signatures
  • Log webhook events for auditing and debugging
  • Always use HTTPS
  • Apply IP allowlisting for enterprise-grade security

​
✅ Summary

Webhooks enable real-time integrations with Trackpilots, including:
  • ⚙️ Automation workflows
  • 📊 Analytics pipelines
  • 🚨 Alert systems
  • 🧠 Productivity monitoring integrations
🚀 More Events Coming SoonAdditional event types and webhook features will be added soon.
For custom webhook requirements, contact team@trackpilots.com.