Skip to main content

Webhooks

Webhooks notify your application in real-time when events happen in cStar. Instead of polling the API, you receive HTTP POST requests whenever a ticket is created, a customer is updated, or a boss is defeated.

How It Works

  1. Register a webhook URL via the API or team settings
  2. Choose which events to subscribe to
  3. cStar sends a signed HTTP POST to your URL when events fire
  4. Your server verifies the signature and processes the event

Event Types

Events follow the pattern resource.action. Subscribe to specific events or use wildcards when creating webhooks.

Tickets

ticket.created Fired when a new ticket is created via app, widget, API, or email
ticket.updated Fired when a ticket status, priority, or assignment changes
ticket.closed Fired when a ticket is resolved or closed
ticket.message_added Fired when a new message is added to a ticket

Customers

customer.created Fired when a new customer is created
customer.updated Fired when customer details are modified

Articles

article.created Fired when a new Library article is created
article.published Fired when an article is published to the Public Library
article.updated Fired when an article content or metadata is modified

Gamification

boss.spawned Fired when a boss appears for the team
boss.defeated Fired when a boss is defeated by the team
player.level_up Fired when a player reaches a new level
achievement.unlocked Fired when a player unlocks an achievement

Surveys

survey.submitted Fired when a customer submits a CSAT survey response

Payload Format

All webhook payloads share the same envelope structure.

Webhook payload 
{
			  "id": "evt_abc123",
			  "type": "ticket.created",
			  "team_id": "your-team-uuid",
			  "created_at": "2025-12-10T14:30:00Z",
			  "data": {
			    "id": "550e8400-e29b-41d4-a716-446655440000",
			    "title": "Cannot log in to my account",
			    "status": "new",
			    "priority": "high"
			  }
			}

Signature Verification

Every webhook request includes a x-cstar-signature header containing an HMAC-SHA256 signature. Always verify this before processing events.

verify-webhook.js 
import crypto from 'crypto';
			
			function verifyWebhook(payload, signature, secret) {
			  const expected = crypto
			    .createHmac('sha256', secret)
			    .update(payload)
			    .digest('hex');
			
			  return crypto.timingSafeEqual(
			    Buffer.from(signature),
			    Buffer.from(expected)
			  );
			}
			
			// Express example
			app.post('/webhook', (req, res) => {
			  const signature = req.headers['x-cstar-signature'];
			  const isValid = verifyWebhook(
			    JSON.stringify(req.body),
			    signature,
			    process.env.WEBHOOK_SECRET
			  );
			
			  if (!isValid) {
			    return res.status(401).json({ error: 'Invalid signature' });
			  }
			
			  const event = req.body;
			  console.log('Event:', event.type, event.data);
			
			  res.status(200).json({ received: true });
			});

Request Headers

x-cstar-signature HMAC-SHA256 signature of the request body
x-cstar-event Event type (e.g., ticket.created)
x-cstar-delivery Unique delivery ID for idempotency
Content-Type application/json

Retries

If your endpoint returns a non-2xx status or doesn't respond within 10 seconds, cStar retries with exponential backoff: 1 minute, 5 minutes, 30 minutes. After 3 failed attempts, the delivery is marked as failed and visible in webhook logs.

Local Testing with the CLI

Use the cStar CLI to forward webhook events to your local development server.

# Forward events to your local server
			cstar listen --forward-to http://localhost:3000/webhook
			
			# In another terminal, trigger a test event
			cstar trigger ticket.created