Webhooks

Webhooks allow you to receive real-time notifications when events occur in your Cliq workspace.

Overview

Instead of polling the API for changes, webhooks push updates to your server as they happen. This is more efficient and provides near-instant notifications.

Setting Up Webhooks

Create a Webhook Endpoint

First, create an endpoint on your server to receive webhook events:

// Express.js example
import express from 'express';
import crypto from 'crypto';

const app = express();
app.use(express.json());

app.post('/webhooks/cliq', (req, res) => {
  // Verify the webhook signature
  const signature = req.headers['x-cliq-signature'];
  const isValid = verifySignature(req.body, signature);
  
  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process the event
  const event = req.body;
  console.log('Received event:', event.type);
  
  // Respond quickly
  res.status(200).send('OK');
  
  // Process asynchronously
  processEvent(event);
});

Register Your Webhook

Go to Settings → Webhooks
Click Create Webhook
Enter your endpoint URL
Select the events you want to receive
Click Create

Event Types

Issue Events

Event	Description
`issue.created`	A new issue was created
`issue.updated`	An issue was updated
`issue.deleted`	An issue was deleted
`issue.status_changed`	An issue's status changed
`issue.assigned`	An issue was assigned

Comment Events

Event	Description
`comment.created`	A new comment was added
`comment.updated`	A comment was edited
`comment.deleted`	A comment was deleted

Project Events

Event	Description
`project.created`	A new project was created
`project.updated`	A project was updated
`project.deleted`	A project was deleted

Member Events

Event	Description
`member.joined`	A new member joined
`member.left`	A member left the workspace
`member.role_changed`	A member's role was changed

Webhook Payload

All webhook payloads follow this structure:

{
  "id": "evt_123456789",
  "type": "issue.created",
  "created_at": "2025-01-15T10:30:00Z",
  "workspace_id": "ws_abc123",
  "data": {
    "id": "issue_xyz789",
    "title": "New feature request",
    "status": "backlog",
    "priority": "medium",
    "created_by": "user_456"
  }
}

Verifying Webhooks

Always verify webhook signatures to ensure requests are from Cliq:

import crypto from 'crypto';

function verifySignature(payload: any, signature: string): boolean {
  const secret = process.env.CLIQ_WEBHOOK_SECRET;
  
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Retry Policy

If your endpoint doesn't respond with a 2xx status code, Cliq will retry:

Attempt	Delay
1	Immediate
2	1 minute
3	5 minutes
4	30 minutes
5	2 hours

After 5 failed attempts, the webhook is marked as failing and you'll receive an email notification.

Best Practices

1. Respond Quickly

Return a 200 response immediately, then process the event asynchronously:

app.post('/webhooks/cliq', async (req, res) => {
  // Respond immediately
  res.status(200).send('OK');
  
  // Process in background
  await queue.add('process-webhook', req.body);
});

2. Handle Duplicates

Webhooks may be delivered more than once. Use the event id to deduplicate:

const processedEvents = new Set();

async function processEvent(event: WebhookEvent) {
  if (processedEvents.has(event.id)) {
    return; // Already processed
  }
  
  processedEvents.add(event.id);
  // Process the event
}

3. Use a Queue

For high-volume webhooks, use a message queue:

import { Queue } from 'bullmq';

const webhookQueue = new Queue('webhooks');

app.post('/webhooks/cliq', async (req, res) => {
  await webhookQueue.add('process', req.body);
  res.status(200).send('OK');
});

// Worker processes events
const worker = new Worker('webhooks', async (job) => {
  const event = job.data;
  // Process event
});

Testing Webhooks

Using the Dashboard

Go to Settings → Webhooks
Select your webhook
Click Send Test Event
Choose an event type
View the response

Using ngrok for Local Development

# Start ngrok
ngrok http 3000

# Use the ngrok URL as your webhook endpoint
# https://abc123.ngrok.io/webhooks/cliq

Troubleshooting

Webhook Not Receiving Events

Check the webhook is enabled in Settings
Verify your endpoint URL is correct
Check your server logs for errors
Ensure your endpoint responds with 200

Invalid Signature Errors

Verify you're using the correct webhook secret
Ensure you're verifying the raw request body
Check for any middleware modifying the body

Events Delayed or Missing

Check the webhook delivery logs in Settings
Look for failed delivery attempts
Verify your endpoint is responding quickly

Webhooks

On this page