Webhook Endpoint Router

Sidekick v1.0.7 introduces a unified webhook endpoint router — a single, centralised layer that receives, verifies, deduplicates, and dispatches incoming webhooks from every connected integration.

Overview

Third-party services (GitHub, Slack, Gmail, and 100+ others) push real-time events to Sidekick via webhooks. Before v1.0.7, each integration managed its own ingestion path. The Webhook Endpoint Router consolidates this into one shared pipeline, making the platform more reliable and easier to extend.

Incoming webhook (any integration)
        │
        ▼
┌─────────────────────────┐
│  Unified Webhook Router │
│                         │
│  1. Route by path       │
│  2. Verify signature    │
│  3. Deduplicate         │
│  4. Create event        │
└───────────┬─────────────┘
            │
            ▼
   Internal event handler

How It Works

1. Integration Registration

Each integration registers two things with the router at startup:

• Webhook path — the URL path segment that uniquely identifies this integration's webhooks (e.g. /webhooks/github, /webhooks/slack).
• Verification method — the mechanism used to confirm that a request genuinely originated from the third-party service.

This registration is declarative and lives alongside the integration's adapter code, so adding a new integration automatically enrolls it in the shared pipeline.

2. Signature Validation

Before any payload is processed, the router runs the integration's registered verification method. Supported verification strategies include:

• HMAC signature (e.g. X-Hub-Signature-256 for GitHub)
• Shared secret header comparison
• Challenge-response handshakes used during webhook registration

Requests that fail verification are rejected with a 401 response and never reach the event layer.

3. Deduplication

Many services retry webhook delivery if they do not receive a timely 2xx response. The router tracks delivery identifiers (typically a header such as X-Webhook-ID or a hash of the payload) and silently discards requests that have already been processed, preventing duplicate actions by your AI agent.

4. Event Creation

Once a webhook passes verification and deduplication, the router normalises the raw payload into a typed internal event and dispatches it to the correct handler. Downstream logic — skill execution, notifications, calendar updates, etc. — receives a consistent event shape regardless of which service sent the original webhook.

Adding Webhook Support to an Integration

If you are building a custom integration adapter, register your webhook with the router by providing:

Field	Type	Description
path	string	Unique URL path for this integration's webhooks
verificationMethod	VerificationConfig	Signature or secret verification configuration
eventSchema	Schema	Shape of the normalised event to emit

Refer to the integration adapter documentation for the full registration API.

Impact on Existing Integrations

No migration is required. All integrations that previously received webhooks are automatically enrolled in the new routing layer. Webhook URLs and secrets do not change.