Webhook Events

Webhooks let you receive real-time HTTP notifications when events occur in your Trackelio workspace. You can use webhooks to integrate Trackelio with external tools, trigger automations, or sync data with your own systems.

Setup

1. Open your Trackelio dashboard.
2. Navigate to Workspaces > Webhooks.
3. Click Create Webhook.
4. Provide the following:
   • URL — The endpoint where Trackelio will send POST requests.
   • Events — Select which events should trigger a delivery.
   • Active/Inactive — Toggle whether the webhook is currently active.
5. Save the webhook.

A secret is automatically generated when you create the webhook. This secret is used for signature verification (see below). Store it securely — you will need it to validate incoming requests.

Events

Event	Description
post.created	Fired when a new post is submitted from any source (widget, public board, or dashboard).
post.status_changed	Fired when a post’s status is updated.
post.assigned	Fired when a post is assigned to a team member.
comment.created	Fired when a comment is added to a post.
nps.submitted	Fired when an NPS response is collected.
csat.submitted	Fired when a CSAT response is collected.
conversation.completed	Fired when a messenger conversation is resolved.

Delivery

When a subscribed event occurs, Trackelio sends an HTTP POST request to your webhook URL with a JSON payload describing the event. Each delivery is logged and includes:

• Status code — The HTTP response code returned by your server.
• Response body — The response body returned by your server (truncated if large).
• Timestamp — When the delivery was sent.
• Failure count — If delivery fails (non-2xx response or timeout), the failure count is incremented and tracked.

You can view the delivery history for each webhook from the webhook detail page in your dashboard.

Signature verification

Every webhook delivery includes a signature header that you should verify to confirm the request originated from Trackelio and was not tampered with.

Header

X-Trackelio-Signature: <signature>

Verification process

1. Read the raw request body as a string (do not parse it first).
2. Compute an HMAC-SHA256 digest of the raw body using your webhook secret as the key.
3. Compare the computed digest against the value in the X-Trackelio-Signature header.

Node.js example

const crypto = require('crypto');

function verifySignature(rawBody, secret, signatureHeader) {
  const computed = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(computed),
    Buffer.from(signatureHeader)
  );
}

// In your webhook handler
app.post('/webhooks/trackelio', (req, res) => {
  const signature = req.headers['x-trackelio-signature'];
  const isValid = verifySignature(req.rawBody, process.env.WEBHOOK_SECRET, signature);

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  const event = req.body;
  console.log('Received event:', event.type);

  // Handle the event
  res.status(200).send('OK');
});

Python example

import hmac
import hashlib

def verify_signature(raw_body: bytes, secret: str, signature_header: str) -> bool:
    computed = hmac.new(
        secret.encode('utf-8'),
        raw_body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(computed, signature_header)

Best practices

• Respond quickly — Return a 2xx status code as soon as possible. Perform heavy processing asynchronously after acknowledging receipt.
• Verify signatures — Always validate the X-Trackelio-Signature header to ensure the request is authentic. Use a constant-time comparison function to prevent timing attacks.
• Handle duplicates — In rare cases, the same event may be delivered more than once. Design your handler to be idempotent.
• Monitor failures — Check the delivery logs in your dashboard periodically to catch and resolve delivery failures.