Webhooks

cstar.webhooks registers endpoints, lists subscriptions, and fires test deliveries. The signing secret comes back exactly once — on creation. Save it then; subsequent reads omit it by design (Stripe pattern).

Create a webhook

create.js

const webhook = await cstar.webhooks.create({
  name: 'Stripe-side ticket sync',
  url: 'https://api.your-app.com/cstar-webhooks',
  events: ['ticket.created', 'ticket.updated', 'ticket.closed']
});

// SAVE THIS NOW. Subsequent reads will not include it.
const secret = webhook.signingSecret;
await secrets.put('CSTAR_WEBHOOK_SECRET', secret);

signingSecret is only present on the create response. Lose it and you'll need to rotate the webhook to get a new one.

List + get

list.js

const { data } = await cstar.webhooks.list({ active: true });

const webhook = await cstar.webhooks.get('whk_abc123');
// webhook.signingSecret is undefined here — that's expected

Update + disable

update.js

// Add an event to the subscription
await cstar.webhooks.update('whk_abc123', {
  events: ['ticket.created', 'ticket.updated', 'ticket.closed', 'customer.created']
});

// Pause without deleting
await cstar.webhooks.update('whk_abc123', { isActive: false });

Delete

delete.js

await cstar.webhooks.delete('whk_abc123');

Send a test delivery

Fire a synthetic event at a registered endpoint and watch the response.

test.js

const result = await cstar.webhooks.test('whk_abc123', 'ticket.created');
// → { deliveryId, event, url, success, status, responseTimeMs, error }

Fire a test event into the dispatcher

Useful when you want to exercise every active webhook on a synthetic event (and any cstar listen session). Equivalent to the CLI's cstar trigger.

trigger.js

const result = await cstar.webhooks.triggerTest({ event: 'ticket.created' });
// → { event, deliveredTo: <count>, ... }

Verify the signature

The receiving end uses the verifier from @cstar.help/js/webhook. Stripe-style X-Signature: t=<unix>,v1=<hex>; legacy sha256=<hex> still accepted for back-compat. See the Webhooks guide for the receiver pattern.

Webhook type

Next up

Webhooks guide Payload format, signature verification, retry policy. Realtime SSE event stream — same events, no endpoint to host. cstar listen Forward live events to localhost in dev.