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 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

Try it

Retrieve all configured webhooks for your team.

Code Examples

bash

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

Responses

200 Array of webhooks

json

{
  "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

json

{
  "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

json

{
  "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

json

{
  "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

bash

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

json

{
  "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

json

{
  "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

json

{
  "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

json

{
  "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

json

{
  "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

bash

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

json

{
  "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

json

{
  "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

json

{
  "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

json

{
  "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

bash

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

json

{
  "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

json

{
  "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

json

{
  "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

json

{
  "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

json

{
  "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

bash

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

Responses

200 Webhook deleted

json

{
  "success": true,
  "data": {
    "deleted": true
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2025-12-10T14:30:00Z"
  }
}

404 Webhook not found

json

{
  "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

json

{
  "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

json

{
  "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

json

{
  "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

bash

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

json

{
  "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

json

{
  "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

json

{
  "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

json

{
  "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

json

{
  "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"
  }
}