Managing Webhooks

Webhooks let your application receive real-time notifications when events occur in Tracore. Each webhook is scoped to a specific schema and environment.

Create a webhook

const webhook = await client.webhooks.create('my-workspace', 'invoice', {
  url: 'https://example.com/webhooks/tracore',
  events: ['run.completed', 'run.failed'],
  env: 'production',
});

console.log(webhook.id); // "wh_abc123"
console.log(webhook.secret); // HMAC signing secret -- store this securely

Events overview

See Event Types for payload details.

Update a webhook

await client.webhooks.update(webhook.id, {
  url: 'https://example.com/webhooks/v2',
  events: ['run.completed'],
});

Disable a webhook

await client.webhooks.update(webhook.id, {
  isActive: false,
});

Delete a webhook

await client.webhooks.delete(webhook.id);

Delivery logs

Every webhook dispatch is logged. You can list deliveries to debug failed deliveries:

const deliveries = await client.webhooks.listDeliveries(webhook.id);

for (const delivery of deliveries.data) {
  console.log(delivery.event); // "run.completed"
  console.log(delivery.statusCode); // 200
  console.log(delivery.success); // true
  console.log(delivery.durationMs); // 142
}

Testing

Tracore includes a built-in test receiver for development. Send a test event to verify your webhook configuration:

await client.webhooks.test(webhook.id);

// Check received events
const events = await client.webhooks.listTestEvents();

Environment scoping

Webhooks are scoped to both a schema and an environment. A webhook created in the staging environment will only fire for events that occur in staging. This prevents test data from triggering production workflows.