Skip to main content

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 string

Unique webhook identifier (whk_ prefix)

name string

Friendly name for the webhook

url string

Delivery URL (HTTPS)

events string[]

Array of subscribed event types

secret string

HMAC signing secret (whsec_ prefix, shown once at creation)

isActive boolean

Whether the webhook is currently active

createdAt datetime

When the webhook was created

updatedAt datetime

Last modification timestamp

Endpoints

GET List WebhooksGET Get WebhookPOST Create WebhookPATCH Update WebhookDELETE Delete WebhookPOST Trigger Test Event
GET /api/v1/teams/{teamId}/webhooks

List Webhooks

Try it

Retrieve all configured webhooks for your team.

Code Examples

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

Responses

200 Array of webhooks
{
  "success": true,
  "data": [
    {
      "id": "whk_a1b2c3d4e5f6",
      "name": "Slack Notifications",
      "url": "https://hooks.slack.com/services/...",
      "events": [
        "ticket.created",
        "ticket.closed"
      ],
      "isActive": true,
      "createdAt": "2025-11-01T10:00:00Z"
    }
  ],
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2025-12-10T14:30:00Z"
  }
}
401 Authentication failed — missing or invalid API key
{
  "success": false,
  "error": {
    "type": "authentication_error",
    "code": "authentication_required",
    "message": "Invalid or expired API key",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}
403 Insufficient permissions — wrong key type or team access
{
  "success": false,
  "error": {
    "type": "authorization_error",
    "code": "insufficient_permissions",
    "message": "Secret key required for this endpoint",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}
429 Rate limit exceeded
{
  "success": false,
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 60 seconds",
    "doc_url": "https://www.cstar.help/developers/api-reference#rate-limiting",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}
GET /api/v1/teams/{teamId}/webhooks/{webhookId}

Get Webhook

Try it

Retrieve a single webhook by ID.

Path Parameters

webhookId string required

The webhook ID (whk_ prefix)

Code Examples

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

Responses

200 The webhook object
{
  "success": true,
  "data": {
    "id": "whk_a1b2c3d4e5f6",
    "name": "Slack Notifications",
    "url": "https://hooks.slack.com/services/...",
    "events": [
      "ticket.created",
      "ticket.closed"
    ],
    "isActive": true,
    "createdAt": "2025-11-01T10:00:00Z",
    "updatedAt": "2025-11-15T12:00:00Z"
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2025-12-10T14:30:00Z"
  }
}
404 Webhook not found
{
  "success": false,
  "error": {
    "type": "not_found_error",
    "code": "RESOURCE_MISSING",
    "message": "Webhook not found",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}
401 Authentication failed — missing or invalid API key
{
  "success": false,
  "error": {
    "type": "authentication_error",
    "code": "authentication_required",
    "message": "Invalid or expired API key",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}
403 Insufficient permissions — wrong key type or team access
{
  "success": false,
  "error": {
    "type": "authorization_error",
    "code": "insufficient_permissions",
    "message": "Secret key required for this endpoint",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}
429 Rate limit exceeded
{
  "success": false,
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 60 seconds",
    "doc_url": "https://www.cstar.help/developers/api-reference#rate-limiting",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}
POST /api/v1/teams/{teamId}/webhooks

Create Webhook

Try it

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://www.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
{
  "success": true,
  "data": {
    "id": "whk_b2c3d4e5f6a7",
    "name": "My Webhook",
    "url": "https://example.com/webhook",
    "events": [
      "ticket.created",
      "ticket.closed"
    ],
    "secret": "whsec_AbCdEf1234567890...",
    "isActive": true,
    "createdAt": "2025-12-10T14:30:00Z"
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2025-12-10T14:30:00Z"
  }
}
401 Authentication failed — missing or invalid API key
{
  "success": false,
  "error": {
    "type": "authentication_error",
    "code": "authentication_required",
    "message": "Invalid or expired API key",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}
403 Insufficient permissions — wrong key type or team access
{
  "success": false,
  "error": {
    "type": "authorization_error",
    "code": "insufficient_permissions",
    "message": "Secret key required for this endpoint",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}
429 Rate limit exceeded
{
  "success": false,
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 60 seconds",
    "doc_url": "https://www.cstar.help/developers/api-reference#rate-limiting",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}
PATCH /api/v1/teams/{teamId}/webhooks/{webhookId}

Update Webhook

Try it

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

Requires a secret API key.

Path Parameters

webhookId string required

The webhook ID (whk_ prefix)

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://www.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
{
  "success": true,
  "data": {
    "id": "whk_b2c3d4e5f6a7",
    "name": "My Webhook",
    "url": "https://example.com/webhook",
    "events": [
      "ticket.created",
      "ticket.updated",
      "ticket.closed"
    ],
    "isActive": true,
    "updatedAt": "2025-12-10T16:00:00Z"
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2025-12-10T16:00:00Z"
  }
}
404 Webhook not found
{
  "success": false,
  "error": {
    "type": "not_found_error",
    "code": "RESOURCE_MISSING",
    "message": "Webhook not found",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}
401 Authentication failed — missing or invalid API key
{
  "success": false,
  "error": {
    "type": "authentication_error",
    "code": "authentication_required",
    "message": "Invalid or expired API key",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}
403 Insufficient permissions — wrong key type or team access
{
  "success": false,
  "error": {
    "type": "authorization_error",
    "code": "insufficient_permissions",
    "message": "Secret key required for this endpoint",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}
429 Rate limit exceeded
{
  "success": false,
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 60 seconds",
    "doc_url": "https://www.cstar.help/developers/api-reference#rate-limiting",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}
DELETE /api/v1/teams/{teamId}/webhooks/{webhookId}

Delete Webhook

Try it

Permanently delete a webhook subscription.

Requires a secret API key.

Path Parameters

webhookId string required

The webhook ID (whk_ prefix)

Code Examples

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

Responses

200 Webhook deleted
{
  "success": true,
  "data": {
    "deleted": true
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2025-12-10T14:30:00Z"
  }
}
404 Webhook not found
{
  "success": false,
  "error": {
    "type": "not_found_error",
    "code": "RESOURCE_MISSING",
    "message": "Webhook not found",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}
401 Authentication failed — missing or invalid API key
{
  "success": false,
  "error": {
    "type": "authentication_error",
    "code": "authentication_required",
    "message": "Invalid or expired API key",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}
403 Insufficient permissions — wrong key type or team access
{
  "success": false,
  "error": {
    "type": "authorization_error",
    "code": "insufficient_permissions",
    "message": "Secret key required for this endpoint",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}
429 Rate limit exceeded
{
  "success": false,
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 60 seconds",
    "doc_url": "https://www.cstar.help/developers/api-reference#rate-limiting",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}
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://www.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
{
  "success": true,
  "data": {
    "event": "ticket.created",
    "eventId": "evt_abc123",
    "test": true,
    "deliveries": []
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2025-12-10T14:30:00Z"
  }
}
400 Invalid event type
{
  "success": false,
  "error": {
    "type": "validation_error",
    "code": "PARAMETER_INVALID",
    "message": "Unknown event type: invalid.event",
    "param": "event",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}
401 Authentication failed — missing or invalid API key
{
  "success": false,
  "error": {
    "type": "authentication_error",
    "code": "authentication_required",
    "message": "Invalid or expired API key",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}
403 Insufficient permissions — wrong key type or team access
{
  "success": false,
  "error": {
    "type": "authorization_error",
    "code": "insufficient_permissions",
    "message": "Secret key required for this endpoint",
    "doc_url": "https://www.cstar.help/developers/api-reference#authentication",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}
429 Rate limit exceeded
{
  "success": false,
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 60 seconds",
    "doc_url": "https://www.cstar.help/developers/api-reference#rate-limiting",
    "request_id": "req_abc123"
  },
  "meta": {
    "timestamp": "2025-12-10T14:30:00Z"
  }
}