Webhooks

Corsair consolidates all incoming webhooks to a single URL. It identifies which integration and service each webhook belongs to, then processes and updates your data automatically.

webhook-handler.ts

import { processWebhook } from "corsair";
import { corsair } from "./corsair";

export async function handleWebhook(req: Request) {
    const result = await processWebhook(
        corsair,
        Object.fromEntries(req.headers),
        await req.json()
    );

    if (result.plugin) {
        console.log(`Handled by ${result.plugin}.${result.action}`);
    }

    return result.response;
}

Note that webhooks are not guaranteed by most senders. If your project requires completely fresh data, add polling for that integration using an api call.

Automatic Routing

Point all your webhooks to a single endpoint. Corsair inspects the headers and payload to determine:

Which integration the webhook is from (Slack, Linear, etc.)
Which event type it represents (message, issue created, etc.)
Which tenant it belongs to (in multi-tenant setups)

Handling Out-of-Order Webhooks

Webhooks don't guarantee delivery order. You might receive an "updated" event before you've processed the "created" event.

Most applications fail here — they don't know about a record, so they can't process its update.

Corsair solves this automatically:

Detects when an update arrives for an unknown record
Fetches the latest data from the API
Creates the record in your database
Processes both the create and update

Your data stays fresh, and no webhooks are lost.

Multi-Tenancy with Webhooks

If you have multi-tenancy enabled, we recommend adding a hashed tenant ID as a query parameter to your webhook URL.

https://api.yourapp.com/webhooks?tenant=hashed_tenant_id

This lets Corsair identify which tenant incoming webhook data belongs to, ensuring proper isolation.

Signature Verification

Corsair automatically verifies webhook signatures using your stored webhook credentials. If a signature doesn't match, the webhook is rejected — protecting you from spoofed requests.

Webhook Hooks

Hooks let you add custom logic that runs every time a webhook is processed. This guarantees your code executes — even when Corsair handles the database update automatically.

corsair.ts

slack({
    authType: "api_key",
    credentials: { botToken: "xoxb-..." },
    webhookHooks: {
        messages: {
            message: {
                before: async (ctx, payload) => {
                    console.log("Incoming message from:", payload.user);
                    return { ctx, payload };
                },
                after: async (ctx, result) => {
                    // This always runs after the webhook is processed
                    await analytics.track("message_received", {
                        channel: result.channel,
                    });
                },
            },
        },
    },
})

Before Hooks

Before hooks run before the webhook is processed. Use them to:

Validate the payload
Log incoming webhooks
Modify the payload before processing
Skip processing by throwing an error

corsair.ts

webhookHooks: {
    messages: {
        message: {
            before: async (ctx, payload) => {
                // Skip bot messages
                if (payload.bot_id) {
                    throw new Error("Ignoring bot message");
                }
                return { ctx, payload };
            },
        },
    },
}

After Hooks

After hooks run after the webhook is processed and the database is updated. Use them to:

Trigger side effects (notifications, syncs)
Update related records in your application
Send data to external services
Log processed webhooks

corsair.ts

webhookHooks: {
    channels: {
        created: {
            after: async (ctx, result) => {
                // Notify your team when a new channel is created
                await sendNotification({
                    title: "New Slack channel",
                    body: `#${result.name} was created`,
                });
            },
        },
    },
    reactions: {
        added: {
            after: async (ctx, result) => {
                // Track reactions for analytics
                await analytics.track("reaction_added", {
                    reaction: result.reaction,
                    channel: result.channel,
                });
            },
        },
    },
}

The key benefit of webhook hooks is they always run when that webhook type is processed. Unlike manually handling webhooks where you might forget to add logging or notifications, hooks ensure your logic is centralized and guaranteed to execute.

corsair.ts

webhookHooks: {
    issues: {
        update: {
            after: async (ctx, result) => {
                // This ALWAYS runs when a Linear issue is updated
                // No matter where the webhook comes from
                await syncToYourDatabase(result);
                await notifyAssignee(result);
                await updateProjectMetrics(result);
            },
        },
    },
}

See Hooks for the full hooks documentation.

Webhooks

Automatic Routing

Handling Out-of-Order Webhooks

Multi-Tenancy with Webhooks

Signature Verification

Webhook Hooks

Before Hooks

After Hooks

Guaranteed Execution

On this page