Quickstart

This guide takes you from zero to a working webhook routing setup. You’ll need a Hookman account — the free tier is enough for everything here.

Time to complete: ~3 minutes.

---

1. Create a project

   A project maps to one webhook integration — for example, your Stripe checkout webhooks, or your GitHub repository webhooks. Each project gets its own Hookman endpoint.

   Go to your dashboard, click New project, and give it:

   • Name — human-readable, shown in the dashboard
   • Default deployment label — a name for the first target, e.g. production
   • Default target URL — where webhooks go until you add a rule

   The slug is derived from the name (lowercased, non-alphanumerics become hyphens) and shown under the field as you type. It forms your endpoint URL and can’t be changed later, so pick the name deliberately.

   Your endpoint will be:

   https://hookman.dev/w/{org}/{project}

   For example: https://hookman.dev/w/acme/payments

   Tip

   Pick a slug that describes the integration, not your app — payments, github-events, notifications. You might have multiple projects for one app.

2. Register your first deployment

   Tell Hookman where your branch deployment lives. Pick your preferred method:

   CLI

   Install the CLI and register your deployment:

   # Install globally (installs the `hookman` binary)
   npm install -g @hookman/cli
   
   # Authenticate — opens your browser
   hookman login
   
   # Register a deployment
   hookman register \
     --org acme \
     --project payments \
     --branch main \
     --url https://myapp.com/api/webhooks/stripe

   Tip

   Set HOOKMAN_API_KEY in your environment and skip the --key flag. See API keys for details.

   Dashboard

   In your project view, click Add deployment, then fill in:

   • Label — the branch name (e.g. main, feature/checkout)
   • Target URL — the full URL including path (e.g. https://myapp.com/api/webhooks/stripe)

   Click Save. The deployment appears in your list immediately.

   GitHub Action

   Add this workflow file to register deployments automatically whenever a preview URL is available:

   .github/workflows/hookman.yml

   name: Hookman webhook routing
   
   on:
     deployment_status:   # fires when Vercel/Netlify/CF Pages posts a preview URL
     pull_request:
       types: [closed]    # clean up on merge
   
   jobs:
     hookman:
       runs-on: ubuntu-latest
       steps:
         - uses: hookman-dev/register-deployment@v1
           with:
             api-key:      ${{ secrets.HOOKMAN_API_KEY }}
             org:          acme
             project:      payments
             webhook-path: /api/webhooks/stripe

   Add HOOKMAN_API_KEY to your repository secrets. See GitHub Action for full options.

3. Set this as your webhook URL

   Configure your webhook provider to POST to your Hookman endpoint. Do this once — you’ll never need to change it.

   Stripe

   # Stripe CLI
   stripe webhooks update wh_xxx \
     --url https://hookman.dev/w/acme/payments

   Or via the Stripe Dashboard: open your endpoint, click Update details, paste your Hookman URL.

   Paddle

   In the Paddle Dashboard: go to Notifications, open your notification destination, update the URL to your Hookman endpoint.

   GitHub

   In your repository: Settings → Webhooks → Edit, update the Payload URL to your Hookman endpoint.

   Other

   Any provider that sends a POST request works — Hookman is provider-agnostic. Find the webhook URL setting in your provider’s dashboard and paste your Hookman endpoint.

4. Switch to a branch deployment

   When you want webhooks to go to a specific branch, set it as active:

   Dashboard

   In your project view, find the deployment you want to activate and click Set active. The green indicator moves to that deployment. All incoming webhooks are now forwarded there.

   CLI

   hookman switch \
     --org acme \
     --project payments \
     --branch feature/checkout

   Note

   Automatic routing available. If your webhook payloads include a branch or environment identifier, you can configure Hookman to route without manual switching. See Routing strategies.

---

Verify it’s working

Send a test webhook from your provider and check the Logs tab in your project dashboard. You should see an entry with:

• The routing method used (e.g. switch)
• The deployment it was forwarded to
• The response status from your target
• The end-to-end latency

If the log shows a routing failure, check troubleshooting common errors.

---

What’s next

• Core concepts — understand projects, orgs, and deployments
• Routing strategies — set up automatic routing without manual switching
• Webhook replay — re-deliver stored webhooks for debugging
• CLI reference — all commands and flags