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

Customers

Articles

Gamification

Community

Surveys

Payload Format

All webhook payloads share the same envelope structure. Fields use snake_case.

Webhook payload 
{
  "id": "evt_ticket_created_1774583010044_abc12345",
  "type": "ticket.created",
  "created_at": "2026-03-06T14:30:00Z",
  "team_id": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "ticket": {
      "id": "25990cb8-cbbf-4671-a973-672cde1cf42d",
      "title": "Cannot log in to my account",
      "status": "new",
      "priority": "high",
      "customer_id": "cd17b730-387d-424e-a50b-eb4a44e543af",
      "customer_name": "Jane Doe",
      "created_at": "2026-03-06T14:30:00Z",
      "dashboard_url": "https://www.cstar.help/team/my-team/tickets?selected=25990cb8-..."
    },
    "customer": {
      "id": "cd17b730-387d-424e-a50b-eb4a44e543af",
      "name": "Jane Doe",
      "email": "jane@example.com"
    }
  }
}

Ticket events include a dashboard_url field — a direct link to the ticket in the cStar dashboard. Use this in Slack messages, emails, or other integrations for one-click access.

Signature Verification

Every webhook request includes an X-Signature header containing an HMAC-SHA256 signature prefixed with sha256=. Always verify this before processing events.

verify-webhook.js 
import crypto from 'crypto';

function verifyWebhook(payload, signature, secret) {
  const expected = 'sha256=' + 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-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-Signature HMAC-SHA256 signature prefixed with sha256=
X-Event-Type Event type (e.g., ticket.created)
X-Event-ID Unique event ID for idempotency
X-Webhook-ID ID of the webhook endpoint that received this delivery
X-Timestamp ISO 8601 timestamp of when the delivery was sent
X-Delivery-Attempt Attempt number (starts at 1)
User-Agent cStar-Webhooks/1.0
Content-Type application/json

Timeouts & Failures

Your endpoint must respond within 10 seconds or the delivery will time out. If your endpoint returns a non-2xx status code, the delivery is marked as failed. All delivery attempts (including failures) are visible in the webhook logs in your team settings. Consecutive failures are tracked per webhook — if failures accumulate, consider checking your endpoint health.

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