Webhooks - Corsair

Webhooks let external services push events to you the moment something happens, like a GitHub star, a Slack message, or a PR merged. You expose one endpoint. Corsair verifies the signature, identifies the plugin, and calls your handler. Three steps: ngrok, register, react.

Step 1: expose a public URL

GitHub and Slack can’t reach localhost. Use ngrok to tunnel your local server:

# Install ngrok — https://ngrok.com/download
ngrok http 3000

You’ll get a URL like https://abc123.ngrok-free.app. Copy it.

Get a stable URL (recommended) Free ngrok accounts get a random URL on every restart, so you’d have to re-register your webhook every time. Claim a free static domain at dashboard.ngrok.com/domains and it’ll never change.

Step 2: create the webhook endpoint

Add one route to your server. All plugins share this single URL:

app/api/webhook/route.ts

import { processWebhook } from 'corsair';
import type { NextRequest } from 'next/server';
import { NextResponse } from 'next/server';
import { corsair } from '@/server/corsair';

export async function POST(request: NextRequest) {
    const headers: Record<string, string> = {};
    request.headers.forEach((value, key) => { headers[key] = value; });

    const body = request.headers.get('content-type')?.includes('application/json')
        ? await request.json()
        : await request.text();

    // Include tenantId if you're using multi-tenancy
    const tenantId = new URL(request.url).searchParams.get('tenantId') ?? undefined;

    const result = await processWebhook(corsair, headers, body, { tenantId });

    if (!result.response) {
        return NextResponse.json({ success: false }, { status: 404 });
    }

    return NextResponse.json(result.response);
}

processWebhook handles everything: it identifies which plugin sent the event, verifies the signature, updates your local database, and runs your hooks.

Step 3: register and react

GitHub
Slack

Register in GitHub:

Go to your repo, then Settings, Webhooks, Add webhook
Set Payload URL: https://your-ngrok-url.ngrok-free.app/api/webhook
Set Content type: application/json
Add a Secret, then save it
Choose events (or “Send me everything”)
Click Add webhook

Store the secret:Pass the secret to the plugin in createCorsair. Corsair uses it to verify incoming webhook signatures.

corsair.ts

github({
    webhookSecret: process.env.GITHUB_WEBHOOK_SECRET,
})

React to events:

corsair.ts

github({
    webhookHooks: {
        starCreated: {
            after: async (ctx, result) => {
                console.log(`⭐ ${result?.data?.sender?.login} starred ${result?.data?.repository?.full_name}`);
            },
        },
        pullRequestOpened: {
            after: async (ctx, result) => {
                const pr = result?.data?.pull_request;
                console.log(`PR opened: "${pr?.title}" by ${pr?.user?.login}`);
            },
        },
        push: {
            after: async (ctx, result) => {
                const branch = result?.data?.ref.replace('refs/heads/', '');
                console.log(`${result?.data?.commits?.length} commit(s) pushed to ${branch}`);
            },
        },
    },
})

Register in Slack:

Go to api.slack.com/apps, then your app
Navigate to Event Subscriptions
Enable events and set the Request URL: https://your-ngrok-url.ngrok-free.app/api/webhook
Slack will send a challenge. Corsair handles verification automatically
Subscribe to bot events: message.channels, team_join, reaction_added

Store the signing secret:Pass the signing secret to the plugin in createCorsair. Corsair uses it to verify incoming webhook signatures.

corsair.ts

slack({
    signingSecret: process.env.SLACK_SIGNING_SECRET,
})

React to events:

corsair.ts

slack({
    webhookHooks: {
        messages: {
            message: {
                after: async (ctx, result) => {
                    if (result.data.bot_id) return; // skip bots
                    console.log(`Message: ${result.data.text}`);
                },
            },
        },
        users: {
            teamJoin: {
                after: async (ctx, result) => {
                    console.log(`New member: ${result.data.user.name}`);
                },
            },
        },
    },
})

How it works

Incoming webhook
    → Corsair reads headers to identify the plugin
    → Verifies signature against stored secret
    → Updates local database
    → Runs your webhookHooks.after() handler

Every plugin shares the same endpoint. You never write routing logic.

What’s next

Workflows

Chain webhook events into multi-step automations.

Multi-tenancy

Scope incoming webhooks per user with ?tenantId= param.

GitHub webhooks

All available GitHub events and payload shapes.

Slack webhooks

All available Slack events and payload shapes.

​Step 1: expose a public URL

​Step 2: create the webhook endpoint

​Step 3: register and react

​How it works

​What’s next

Workflows

Multi-tenancy

GitHub webhooks

Slack webhooks

Step 1: expose a public URL

Step 2: create the webhook endpoint

Step 3: register and react

How it works

What’s next