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.Configure a webhook endpoint URL in your dashboard
- 2.Select which events you want to receive
- 3.ClockEye sends a POST request to your endpoint when events occur
- 4.Your server processes the webhook and responds with 200 OK
Available Events
Subscribe to any of the following webhook events.
time_entry.createdFired when a new time entry is created
time_entry.updatedFired when a time entry is modified
time_entry.deletedFired when a time entry is deleted
screenshot.capturedFired when a screenshot is captured and uploaded
user.invitedFired when a new user is invited to the workspace
user.activatedFired when an invited user accepts and activates their account
project.createdFired when a new project is created
timesheet.submittedFired when a user submits their timesheet for approval
timesheet.approvedFired when a timesheet is approved
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:
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}`)
);
}- 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