Webhooks

Webhooks notify your application in real-time when events happen in cStar. Subscribe to ticket, customer, article, and gamification events.

The Webhook object

id uuid

Unique webhook identifier

name string

Friendly name for the webhook

url string

Delivery URL (HTTPS)

events string[]

Array of subscribed event types

secret string

HMAC signing secret (shown once at creation)

is_active boolean

Whether the webhook is currently active

created_at datetime

When the webhook was created

updated_at datetime

Last modification timestamp

Endpoints

GET List Webhooks GET Get Webhook POST Create Webhook PATCH Update Webhook DELETE Delete Webhook POST Trigger Test Event

GET /api/v1/teams/{teamId}/webhooks

List Webhooks

Retrieve all configured webhooks for your team.

Code Examples

curl -X GET "https://app.cstar.help/api/v1/teams/{teamId}/webhooks" \
			  -H "Authorization: Bearer sk_live_your_key"

Responses

200 Array of webhooks

{
			  "data": [
			    {
			      "id": "wh_001",
			      "name": "Slack Notifications",
			      "url": "https://hooks.slack.com/services/...",
			      "events": [
			        "ticket.created",
			        "ticket.closed"
			      ],
			      "is_active": true,
			      "created_at": "2025-11-01T10:00:00Z"
			    }
			  ]
			}

401 Authentication failed — missing or invalid API key

{
			  "error": {
			    "code": "UNAUTHORIZED",
			    "message": "Invalid or expired API key"
			  }
			}

403 Insufficient permissions — wrong key type or team access

{
			  "error": {
			    "code": "FORBIDDEN",
			    "message": "Secret key required for this endpoint"
			  }
			}

429 Rate limit exceeded

{
			  "error": {
			    "code": "RATE_LIMITED",
			    "message": "Rate limit exceeded. Try again in 60 seconds",
			    "retryAfter": 60
			  }
			}

GET /api/v1/teams/{teamId}/webhooks/{webhookId}

Get Webhook

Retrieve a single webhook by ID.

Path Parameters

webhookId uuid required

The webhook ID

Code Examples

curl -X GET "https://app.cstar.help/api/v1/teams/{teamId}/webhooks/{webhookId}" \
			  -H "Authorization: Bearer sk_live_your_key"

Responses

200 The webhook object

{
			  "data": {
			    "id": "wh_001",
			    "name": "Slack Notifications",
			    "url": "https://hooks.slack.com/services/...",
			    "events": [
			      "ticket.created",
			      "ticket.closed"
			    ],
			    "is_active": true,
			    "created_at": "2025-11-01T10:00:00Z",
			    "updated_at": "2025-11-15T12:00:00Z"
			  }
			}

404 Webhook not found

{
			  "error": {
			    "code": "resource_missing",
			    "message": "Webhook not found"
			  }
			}

401 Authentication failed — missing or invalid API key

{
			  "error": {
			    "code": "UNAUTHORIZED",
			    "message": "Invalid or expired API key"
			  }
			}

403 Insufficient permissions — wrong key type or team access

{
			  "error": {
			    "code": "FORBIDDEN",
			    "message": "Secret key required for this endpoint"
			  }
			}

429 Rate limit exceeded

{
			  "error": {
			    "code": "RATE_LIMITED",
			    "message": "Rate limit exceeded. Try again in 60 seconds",
			    "retryAfter": 60
			  }
			}

POST /api/v1/teams/{teamId}/webhooks

Create Webhook

Create a new webhook subscription. The signing secret is returned once — save it immediately.

Requires a secret API key. Save the returned secret — it cannot be retrieved again.

Request Body

name string required

Friendly name

url string required

Delivery URL (must be HTTPS)

events string required

Comma-separated event types to subscribe to

Code Examples

curl -X POST "https://app.cstar.help/api/v1/teams/{teamId}/webhooks" \
			  -H "Authorization: Bearer sk_live_your_key" \
			  -H "Content-Type: application/json" \
			  -d '{
			    "name": "My Webhook",
			    "url": "https://example.com/webhook",
			    "events": "ticket.created,ticket.closed"
			  }'

Responses

201 Webhook created with signing secret

{
			  "data": {
			    "id": "wh_002",
			    "name": "My Webhook",
			    "url": "https://example.com/webhook",
			    "events": [
			      "ticket.created",
			      "ticket.closed"
			    ],
			    "secret": "whsec_AbCdEf1234567890...",
			    "is_active": true,
			    "created_at": "2025-12-10T14:30:00Z"
			  }
			}

401 Authentication failed — missing or invalid API key

{
			  "error": {
			    "code": "UNAUTHORIZED",
			    "message": "Invalid or expired API key"
			  }
			}

403 Insufficient permissions — wrong key type or team access

{
			  "error": {
			    "code": "FORBIDDEN",
			    "message": "Secret key required for this endpoint"
			  }
			}

429 Rate limit exceeded

{
			  "error": {
			    "code": "RATE_LIMITED",
			    "message": "Rate limit exceeded. Try again in 60 seconds",
			    "retryAfter": 60
			  }
			}

PATCH /api/v1/teams/{teamId}/webhooks/{webhookId}

Update Webhook

Update an existing webhook. Use this to change the URL, events, or toggle active status.

Requires a secret API key.

Path Parameters

webhookId uuid required

The webhook ID

Request Body

name string

Friendly name

url string

Delivery URL (must be HTTPS)

events string

Comma-separated event types

isActive boolean

Enable or disable the webhook

Code Examples

curl -X PATCH "https://app.cstar.help/api/v1/teams/{teamId}/webhooks/{webhookId}" \
			  -H "Authorization: Bearer sk_live_your_key" \
			  -H "Content-Type: application/json" \
			  -d '{ "events": "ticket.created,ticket.updated,ticket.closed" }'

Responses

200 Updated webhook

{
			  "data": {
			    "id": "wh_002",
			    "name": "My Webhook",
			    "url": "https://example.com/webhook",
			    "events": [
			      "ticket.created",
			      "ticket.updated",
			      "ticket.closed"
			    ],
			    "is_active": true,
			    "updated_at": "2025-12-10T16:00:00Z"
			  }
			}

404 Webhook not found

{
			  "error": {
			    "code": "resource_missing",
			    "message": "Webhook not found"
			  }
			}

401 Authentication failed — missing or invalid API key

{
			  "error": {
			    "code": "UNAUTHORIZED",
			    "message": "Invalid or expired API key"
			  }
			}

403 Insufficient permissions — wrong key type or team access

{
			  "error": {
			    "code": "FORBIDDEN",
			    "message": "Secret key required for this endpoint"
			  }
			}

429 Rate limit exceeded

{
			  "error": {
			    "code": "RATE_LIMITED",
			    "message": "Rate limit exceeded. Try again in 60 seconds",
			    "retryAfter": 60
			  }
			}

DELETE /api/v1/teams/{teamId}/webhooks/{webhookId}

Delete Webhook

Permanently delete a webhook subscription.

Requires a secret API key.

Path Parameters

webhookId uuid required

The webhook ID

Code Examples

curl -X DELETE "https://app.cstar.help/api/v1/teams/{teamId}/webhooks/{webhookId}" \
			  -H "Authorization: Bearer sk_live_your_key"

Responses

200 Webhook deleted

{
			  "data": {
			    "deleted": true
			  }
			}

404 Webhook not found

{
			  "error": {
			    "code": "resource_missing",
			    "message": "Webhook not found"
			  }
			}

401 Authentication failed — missing or invalid API key

{
			  "error": {
			    "code": "UNAUTHORIZED",
			    "message": "Invalid or expired API key"
			  }
			}

403 Insufficient permissions — wrong key type or team access

{
			  "error": {
			    "code": "FORBIDDEN",
			    "message": "Secret key required for this endpoint"
			  }
			}

429 Rate limit exceeded

{
			  "error": {
			    "code": "RATE_LIMITED",
			    "message": "Rate limit exceeded. Try again in 60 seconds",
			    "retryAfter": 60
			  }
			}

POST /api/v1/teams/{teamId}/webhooks/trigger-test

Trigger Test Event

Fire a test webhook event to all active webhooks and CLI listeners. Useful for testing your integration.

Requires a secret API key. Also available via CLI: `cstar trigger <event>`

Request Body

event string required

Event type to fire

Code Examples

curl -X POST "https://app.cstar.help/api/v1/teams/{teamId}/webhooks/trigger-test" \
			  -H "Authorization: Bearer sk_live_your_key" \
			  -H "Content-Type: application/json" \
			  -d '{ "event": "ticket.created" }'

Responses

200 Test event dispatched

{
			  "data": {
			    "event": "ticket.created",
			    "eventId": "evt_abc123",
			    "deliveries": []
			  }
			}

400 Invalid event type

{
			  "error": {
			    "code": "parameter_invalid",
			    "message": "Unknown event type: invalid.event",
			    "param": "event"
			  }
			}

401 Authentication failed — missing or invalid API key

{
			  "error": {
			    "code": "UNAUTHORIZED",
			    "message": "Invalid or expired API key"
			  }
			}

403 Insufficient permissions — wrong key type or team access

{
			  "error": {
			    "code": "FORBIDDEN",
			    "message": "Secret key required for this endpoint"
			  }
			}

429 Rate limit exceeded

{
			  "error": {
			    "code": "RATE_LIMITED",
			    "message": "Rate limit exceeded. Try again in 60 seconds",
			    "retryAfter": 60
			  }
			}