Inspect, debug and replay webhooks with ease.
Hookscope is a developer tool for receiving, inspecting and testing webhooks. It provides temporary and permanent webhook endpoints that allow developers to capture incoming HTTP requests, analyze payloads, debug integrations and replay events during development.
Webhook integrations are used everywhere — payment systems, GitHub events, CI/CD pipelines, automation platforms, SaaS integrations and internal services. Debugging these integrations is often difficult because developers need to expose local applications, inspect incoming data, verify headers and reproduce failed events.
Hookscope simplifies this process by providing a dedicated webhook inbox where you can receive requests, inspect every detail and simulate different responses.
Hookscope is designed for:
- Backend developers building and debugging webhook integrations.
- Frontend developers testing communication with external services.
- DevOps engineers validating CI/CD and automation workflows.
- API developers testing request formats, headers and retry behavior.
- Teams building SaaS integrations that need visibility into incoming events.
Try Hookscope without installation:
The easiest way to use Hookscope is through the live instance:
No installation is required.
- Open Hookscope.
- Copy your webhook endpoint.
- Configure your service to send webhook requests to this URL.
- Inspect incoming requests directly in the dashboard.
Example endpoint:
https://hookscope.ycode.pl/hook/SESSION_ID
Hookscope can be deployed on your own infrastructure using Docker Compose.
Before running Hookscope, install:
- Docker
- Docker Compose
Clone the repository:
git clone https://github.com/your-org/hookscope.git
cd hookscopeCreate environment files:
cp .env.example .env
cp ./apps/api/.env.example ./apps/api/.envAdjust environment variables according to your environment.
Run:
docker compose up -dRun database migrations:
npm run db:migrateThe stack includes:
- Hookscope frontend
- API server
- PostgreSQL database
- required infrastructure services
After startup, open:
http://localhost:{PORT_FROM_ENV}
Hookscope allows you to customize webhook endpoint behavior using the strategy.yml file.
The strategy file defines rules that decide how incoming webhook requests should be handled. Each rule can match specific requests, evaluate custom conditions and return different responses depending on the result.
This makes it possible to simulate external webhook providers, test error handling, validate payloads and reproduce different integration scenarios.
A strategy file contains a list of rules:
rules:
- name: example-rule
match:
method: POST
conditions:
- js: |
context.body.example === true
ok:
status: 200
body:
message: "accepted"
fail:
status: 400
body:
message: "invalid request"
- name: fallback
response:
status: 404
body:
error: "not found"Each rule represents a possible request handling scenario.
Example:
- name: product-webhookThe name field is used to identify the rule.
Rules can define which requests they apply to using the match section.
Example:
match:
method: POSTA rule can be limited based on request properties such as:
- HTTP method
- request details
- incoming webhook data
Only matching requests are evaluated by the rule.
Conditions allow you to execute custom JavaScript logic against the incoming request.
Example:
conditions:
- js: |
context.body.product_id === 10The context object contains information about the received webhook request.
You can use it to inspect:
- request body
- headers
- query parameters
- request metadata
The condition result determines which response is returned.
When the JavaScript condition returns true, Hookscope uses the ok response.
Example:
ok:
status: 200
headers:
"x-response": "accepted"
body:
message: "product accepted"Supported options:
status— HTTP response status codeheaders— custom response headersbody— response payload
When the condition returns false, Hookscope uses the fail response.
Example:
fail:
status: 400
body:
message: "wrong product"This can be used to simulate validation errors or rejected webhook events.
A rule without conditions can act as a fallback handler.
Example:
- name: fallback
response:
status: 404
body:
error: "not found"The fallback rule is useful for defining the default behavior when no previous rule matches.
rules:
- name: product-webhook
match:
method: POST
conditions:
- js: |
context.body.product_id === 10
ok:
status: 200
headers:
"x-response": "accepted"
body:
message: "product accepted"
fail:
status: 400
body:
message: "wrong product"
- name: fallback
response:
status: 404
body:
error: "not found"With this configuration:
POSTrequests containingproduct_id: 10receive200 OK.- Other products receive
400 Bad Request. - Requests that do not match any rule receive
404 Not Found.
The strategy.yml file can be used for:
- testing webhook retries,
- simulating provider failures,
- validating payload handling,
- mocking third-party integrations,
- testing different API responses without changing application code.
Contributions are welcome.
To contribute:
- Fork the repository.
- Create a feature branch.
git checkout -b feature/my-feature- Make your changes.
- Test your implementation.
- Open a pull request.
When contributing, please:
- keep changes focused,
- add documentation for new features,
- follow the existing project structure,
- include tests where applicable.
MIT License
Copyright (c) Hookscope contributors