GitHub Action

The hookman-dev/register-deployment GitHub Action registers and removes deployments automatically as part of your CI/CD workflow. It’s the zero-friction way to keep Hookman in sync with your branch deployments.

How it works

The action listens on deployment_status events. This event fires after your deployment platform (Vercel, Netlify, Cloudflare Pages, Render, Railway, etc.) has finished deploying and has posted the preview URL back to GitHub. That’s the earliest moment the preview URL is known.

On pull_request: closed, the action removes the deployment from Hookman — keeping your deployment list clean after merges.

Note

Why deployment_status and not push?

push fires before the preview URL exists. deployment_status fires after the platform has deployed and reported success. Using push would require you to predict the preview URL format — fragile and platform-specific. deployment_status gives you the real URL from the platform itself.

Supported platforms

Any platform that creates GitHub Deployments and posts a deployment_status works automatically:

• Vercel
• Netlify
• Cloudflare Pages
• Render
• Railway
• Fly.io (with GitHub integration enabled)

Platforms that don’t post deployment_status events require the url input (see Manual URL below).

Basic usage

.github/workflows/hookman.yml

name: Hookman webhook routing

on:
  deployment_status:
  pull_request:
    types: [closed]

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’s Settings → Secrets and variables → Actions.

Inputs

Input	Required	Default	Description
api-key	Yes	—	Hookman API key. Use a repository secret.
org	Yes	—	Your Hookman org slug.
project	Yes	—	Your Hookman project slug.
webhook-path	No	''	Path to append to the deployment URL. E.g. /api/webhooks/stripe.
action	No	auto	register, remove, or auto. auto registers on deployment_status: success and removes on pull_request: closed.
url	No	—	Override the deployment URL (bypasses GitHub Deployment URL detection).
branch	No	—	Override the branch name (defaults to the ref from the event context).

Outputs

Output	Description
deployment-url	The full target URL that was registered (deployment URL + webhook-path).
hookman-endpoint	Your Hookman endpoint URL for this project.

Examples

Multiple projects from one workflow

- uses: hookman-dev/register-deployment@v1
  with:
    api-key:      ${{ secrets.HOOKMAN_API_KEY }}
    org:          acme
    project:      payments
    webhook-path: /api/webhooks/stripe

- uses: hookman-dev/register-deployment@v1
  with:
    api-key:      ${{ secrets.HOOKMAN_API_KEY }}
    org:          acme
    project:      github-events
    webhook-path: /api/webhooks/github

Manual URL

For platforms that don’t post deployment_status, construct the URL yourself and pass it via the url input:

on:
  push:
    branches: ['feature/**', 'fix/**']

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
          # Construct your platform's preview URL pattern manually:
          url:          https://${{ github.head_ref }}.myapp.pages.dev

Print the Hookman endpoint after registration

- uses: hookman-dev/register-deployment@v1
  id: hookman
  with:
    api-key:      ${{ secrets.HOOKMAN_API_KEY }}
    org:          acme
    project:      payments
    webhook-path: /api/webhooks/stripe

- run: |
    echo "Hookman endpoint: ${{ steps.hookman.outputs.hookman-endpoint }}"
    echo "Forwarding to: ${{ steps.hookman.outputs.deployment-url }}"

Only run on specific branches

jobs:
  hookman:
    runs-on: ubuntu-latest
    # Only run for feature branches, not main/staging
    if: |
      github.event_name == 'deployment_status' &&
      !contains(fromJSON('["main", "staging"]'), github.event.deployment.ref)
    steps:
      - uses: hookman-dev/register-deployment@v1
        with:
          api-key:  ${{ secrets.HOOKMAN_API_KEY }}
          org:      acme
          project:  payments

Troubleshooting

The action skips with “Deployment status is not success”

This is expected — the action only registers on success status. Platforms post several deployment_status events per deploy (e.g. pending, in_progress, success). The action ignores all but success.

The action can’t find the deployment URL

Not all deployment_status payloads include environment_url. The action falls back to target_url. If neither is present, use the url input to provide it manually.

The branch name contains slashes and breaks the URL

Hookman handles this automatically — branch labels with slashes are URL-encoded when used as routing keys. You don’t need to sanitise the branch name.

I’m using Vercel but the action isn’t firing

Vercel creates GitHub Deployments by default. Check that the Vercel GitHub App has permission to create deployments in your repository: Repository Settings → Integrations → Vercel.