Webhooks Reference

Receive real-time notifications when events occur in ClockEye.

Overview

Webhooks allow your application to receive real-time notifications when events occur in ClockEye. Instead of polling the API, configure webhook endpoints to receive instant updates.

How Webhooks Work

  1. 1.Configure a webhook endpoint URL in your dashboard
  2. 2.Select which events you want to receive
  3. 3.ClockEye sends a POST request to your endpoint when events occur
  4. 4.Your server processes the webhook and responds with 200 OK

Available Events

Subscribe to any of the following webhook events.

time_entry.created

Fired when a new time entry is created

iduser_idproject_idstart_timeduration
time_entry.updated

Fired when a time entry is modified

idchangesupdated_at
time_entry.deleted

Fired when a time entry is deleted

iddeleted_at
screenshot.captured

Fired when a screenshot is captured and uploaded

iduser_idtime_entry_idurlactivity_level
user.invited

Fired when a new user is invited to the workspace

idemailroleinvited_by
user.activated

Fired when an invited user accepts and activates their account

idemailactivated_at
project.created

Fired when a new project is created

idnamecreated_by
timesheet.submitted

Fired when a user submits their timesheet for approval

iduser_idperiod_startperiod_endtotal_hours
timesheet.approved

Fired when a timesheet is approved

idapproved_byapproved_at

Webhook Payload

All webhook payloads follow a consistent format:

{
  "id": "evt_abc123xyz",
  "type": "time_entry.created",
  "created_at": "2024-01-15T10:30:00Z",
  "data": {
    "id": "te_def456",
    "user_id": "usr_xyz789",
    "project_id": "prj_abc123",
    "start_time": "2024-01-15T09:00:00Z",
    "duration": 3600,
    "description": "Working on feature X"
  }
}

Security

Verify webhook authenticity to ensure requests come from ClockEye.

Signature Verification

Each webhook includes a signature header that you should verify:

X-ClockEye-Signature: sha256=abc123...

Verification Code Example

import crypto from 'crypto';

function verifyWebhookSignature(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(`sha256=${expectedSignature}`)
  );
}
Security Best Practices
  • Always verify webhook signatures
  • Use HTTPS endpoints only
  • Respond quickly (within 5 seconds) to avoid timeouts
  • Implement idempotency to handle duplicate deliveries

Implementation Examples

Node.js / Express

app.post('/webhooks/clockeye', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-clockeye-signature'];
  const payload = req.body.toString();

  if (!verifyWebhookSignature(payload, signature, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(payload);

  switch (event.type) {
    case 'time_entry.created':
      handleTimeEntryCreated(event.data);
      break;
    case 'screenshot.captured':
      handleScreenshotCaptured(event.data);
      break;
    // ... handle other events
  }

  res.status(200).send('OK');
});

Retry Policy

If your endpoint fails to respond with a 2xx status code, ClockEye will retry the webhook:

  • First retry: 1 minute after failure
  • Second retry: 5 minutes after failure
  • Third retry: 30 minutes after failure
  • Final retry: 2 hours after failure

Related Resources