Test webhook handlers in GitHub Actions.
Send real webhooks to the application running in your job and catch delivery, routing, and signature bugs before they ship.
Fixture tests only cover the request you recreated.
A live test can add the parts that fixtures leave out: the public URL, TLS connection, original headers, raw request body, and signature verification.
Catch integration bugs before merge
Exercise the request path all the way to your handler. Problems with routing, body parsing, headers, and signatures show up in CI instead of production.
Test without a staging deployment
Your application stays inside the GitHub Actions runner while Hookbridge forwards real deliveries to it. There is no public test server to deploy or maintain.
Give every run its own endpoint
Each job gets a short-lived receive URL, so parallel runs do not share webhook deliveries or depend on a long-lived test endpoint.
Add it around your existing test step.
Start your application in the job as usual. The Action supplies a receive URL for the test, forwards incoming webhooks to the application, and removes the endpoint afterward.
# Set up a temporary endpoint and listener
- uses: hookbridge/hookbridge-action@v1
id: hookbridge
with:
api-key: ${{ secrets.HOOKBRIDGE_API_KEY }}
port: "3000"
# Run your own test against the receive URL
- run: ./run-my-webhook-tests.sh
env:
WEBHOOK_URL: ${{ steps.hookbridge.outputs.url }}
# Clean up even when the test fails
- uses: hookbridge/hookbridge-action/cleanup@v1
if: always()
with:
api-key: ${{ secrets.HOOKBRIDGE_API_KEY }}
endpoint-id: ${{ steps.hookbridge.outputs.endpoint-id }}
listener-pid: ${{ steps.hookbridge.outputs.listener-pid }}
listener-identity: ${{ steps.hookbridge.outputs.listener-identity }}Use the application routes and test tools you already have.
Any test runner
Pass the receive URL to a shell script, integration test, or end-to-end test through an environment variable.
Port or URL forwarding
Forward to a local port or provide the full URL for a route such as /webhooks/stripe.
No CLI setup
The Action downloads a pinned Hookbridge CLI release and verifies its checksum before it runs.
Detailed guides for GitHub Actions and other CI systems.
GitHub Actions tutorial
Learn what fixture tests miss, how to wait for asynchronous delivery, and how to keep the receive URL out of logs.
Read the CI tutorial →Other CI systems
The Action is built on the Hookbridge CLI. Use the CLI directly in GitLab CI, CircleCI, Jenkins, or another CI system.
Explore the Hookbridge CLI →Start testing webhook handlers in CI.
The guide includes a complete workflow and reference for the available inputs and outputs.