> ## Documentation Index
> Fetch the complete documentation index at: https://developer.trackpilots.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Configure webhooks to receive real-time event notifications from Trackpilots

<Callout type="info">
  🔔 **Real-time Event Notifications**

  Webhooks allow Trackpilots to send real-time event data to your application whenever an event occurs.
</Callout>

***

## 📌 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](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
     ```text theme={null}
     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**.

```js theme={null}
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 using constant-time comparison (prevents timing attacks)
      const sigBuffer = Buffer.from(signature, "hex");
      const expectedBuffer = Buffer.from(expectedSignature, "hex");
      if (
        sigBuffer.length !== expectedBuffer.length ||
        !crypto.timingSafeEqual(sigBuffer, expectedBuffer)
      ) {
        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 with Simulations

The fastest way to verify your endpoint is the built-in **Webhook Simulations** tool — no need to trigger a real desktop event.

👉 [Open Simulations](https://app.trackpilots.com/developer-tools/simulations)

It sends a real, signed payload to your endpoint and shows you the HTTP status, latency, sent payload, and your server's response — all in one place. See the [Simulations guide](/docs/developer-tools/simulations) for full details.

***

## 🧪 Test Webhooks Locally

You can also 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

<Callout type="warning">
  ⚠️ **Ensure High Availability**

  Make sure your webhook endpoint is publicly accessible and highly available to avoid missed events.
</Callout>

* Validate incoming webhook payloads.
* Log webhook requests for debugging and auditing.
* Handle duplicate events gracefully.
* Secure your endpoint using signature validation (recommended).

<Callout type="warning">
  🛡️ **Always verify webhook signatures:**
  Never trust incoming webhook requests without validation.
</Callout>

## 🔒 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

***

<Callout type="info">
  🚀 **More Events Coming Soon**

  Additional event types and webhook features will be added soon.\
  For custom webhook requirements, contact **[team@trackpilots.com](mailto:team@trackpilots.com)**.
</Callout>