​

Webhooks & Event-Driven Automation

​

How It Works

1. An external service sends a POST to /webhooks/:provider.
2. The webhook route verifies the request signature (if configured).
3. The event type is extracted from provider-specific headers or body fields.
4. The WebhookSessionBridge formats the event into a natural-language prompt.
5. That prompt can trigger a new Savant session — the agent takes it from there.

​

Supported Providers

​

Configuration

​

Registering a Webhook URL

https://your-savant-server.com/webhooks/{provider}

• GitHub: https://savant.example.com/webhooks/github
• Bitbucket: https://savant.example.com/webhooks/bitbucket
• JIRA: https://savant.example.com/webhooks/jira
• Zendesk: https://savant.example.com/webhooks/zendesk
• Datadog: https://savant.example.com/webhooks/datadog

​

Configuring Secrets

import { WebhookRoute } from './routes/webhooks.js';

const webhook_route = new WebhookRoute();

// Configure secrets per provider
webhook_route.configure_provider('github', { secret: process.env.GITHUB_WEBHOOK_SECRET });
webhook_route.configure_provider('bitbucket', { secret: process.env.BITBUCKET_WEBHOOK_SECRET });
webhook_route.configure_provider('jira', { secret: process.env.JIRA_WEBHOOK_SECRET });
webhook_route.configure_provider('zendesk', { secret: process.env.ZENDESK_WEBHOOK_SECRET });

// Disable a provider entirely
webhook_route.configure_provider('datadog', { enabled: false });

​

Slack URL Verification

​

Event Handlers

webhook_route.on_event(async (event) => {
    console.log(`[${event.provider}] ${event.event_type}`);
    console.log('Payload:', event.payload);

    // Create a Savant session from the event
    const prompt = WebhookSessionBridge.format_prompt(event);
    // ... trigger a new session with this prompt
});

​

WebhookEvent Shape

interface WebhookEvent {
    provider: string;          // "github", "bitbucket", "jira", etc.
    event_type: string;        // "push", "pullrequest:created", "ticket_created", etc.
    payload: Record<string, unknown>;  // Raw webhook body
    headers: Record<string, string>;   // Request headers
    received_at: string;       // ISO timestamp
}

​

WebhookSessionBridge

​

Example: Auto-Review PRs on Push

1. GitHub/Bitbucket sends a pull_request.opened webhook to Savant.
2. The WebhookSessionBridge creates a prompt: “Review PR #42…”
3. A new Savant session starts. The agent uses github_get_pr_diff (or bitbucket_get_pr_diff) to read the changes.
4. The agent reviews the code, checking for patterns in the Knowledge Store.
5. The agent posts a review comment via github_post_review (or bitbucket_post_comment).
6. The agent updates the linked JIRA ticket via jira_transition_issue.
7. The agent posts a summary to Slack via slack_send_message.

​

Example: Auto-Triage Zendesk Tickets

1. Zendesk sends a ticket_created webhook.
2. Savant reads the ticket details via zendesk_get_ticket.
3. The agent searches the Knowledge Store for similar past tickets and resolutions.
4. The agent looks up the customer in internal systems (via custom client tools).
5. The agent drafts a response and posts it via zendesk_add_comment.
6. The agent updates the ticket priority and tags via zendesk_update_ticket.

​

Safety

• ToolGuard gates every tool invocation — destructive actions (merging PRs, closing tickets) require approval unless YOLO mode is enabled.
• FlowGuard prevents runaway execution — a single webhook cannot trigger an infinite chain of agent actions.
• Webhook handlers run asynchronously and failures in one handler do not block others.