Testing GitHub Webhook Integrations in CI Without Live Events
Signed fixtures and a stateful simulator make GitHub webhook tests repeatable.

Testing GitHub webhook integrations in CI without live events requires deterministic payload injection, using realistic, correctly signed fixtures sent directly to the running handler. When the handler calls a stateful API, a local simulator must preserve resource state across those calls so tests can verify their order and effects. This approach tests the integration without production access or dependence on GitHub firing an event.
Why CI pipelines struggle with webhook integrations
A REST integration test can initiate the request whose result it needs to inspect. A webhook test depends on an external provider to initiate that request, asynchronously and outside the pipeline’s control. A test that waits for a real push event therefore depends on more than the handler change it is supposed to evaluate.
Local receipt during development, CI verification without the provider, and production failure reproduction are distinct problems. A tunnel can help with the first while introducing uncertainty into the second. Free-tier tunnel URLs can change, sessions can expire between retries, and sensitive payload data passes through a third party. Live sandbox calls retain the external dependency even when the endpoint is reachable. Reachability is not the same as repeatability.
The resulting coverage gap can remain silent. A provider changes a field name, timestamp format, or signing scheme, but the build stays green because it never tests a delivery with that change. The integration then breaks in production. Tunnels and ngrok loops do not resolve that structural gap because they still require an event source the pipeline does not control.
What GitHub actually sends and why the raw bytes matter
A GitHub webhook delivery includes a request body and headers that identify its event, delivery, and signature. GitHub uses HMAC-SHA256 over the raw body with the webhook secret configured in repository or GitHub App settings. The result appears in X-Hub-Signature-256, prefixed with sha256=. Those bytes define the verification input. A parsed object is not an equivalent substitute.
JSON parsing followed by serialization can change whitespace or key order without changing the apparent data. Those changes still invalidate the signature because verification operates on bytes. The handler must therefore read and verify the raw body before parsing it. Unlike Stripe, GitHub does not sign a timestamp, so container clock tolerance is not part of this check. The signature also provides no replay protection by itself.
The body’s structure deserves the same attention. A captured push event exposes the commits array, the refs/heads/main ref format, and the SHA fields the handler will actually receive. Relevant event families include push, pull_request, issues, installation, and workflow_run. Their uses range from deployment triggers and review automation to GitHub App lifecycle handling and post-CI artifact processing. The fixture library needs the events the integration handles, in the same structure they have when they arrive.
Capturing representative payloads in development
Development-time capture supplies that structure without guessing from documentation. The purpose is to obtain representative deliveries once and preserve them as test inputs. Tool choice follows the development need. A short local iteration loop, an inspectable public endpoint, and a retained failure history serve different purposes.
It needs no public URL and preserves X-Hub-Signature-256 unchanged. Repository forwarding can target push and pull_request, while organisation forwarding requires the admin:org_hook scope. This suits iteration against a controlled repository. It is insufficient when the same payload needs repeated replay or sharing with a teammate.
An HTTPS tunnel such as Pinggy provides a public URL, with its Web Debugger adding header and body inspection plus Replay and the ability to edit requests before replaying them. For capture that needs to last longer, relay services such as webhooks.cc have a persistent endpoint, keep a history, and offer exact-bytes replay and automatic signature verification. Smee.io is another common starting point, but its captures live in the browser tab, disappear when it closes, and cannot be replayed across sessions. It forwards the signature header without verifying it.
Regardless of the capture mechanism, the useful output is a fixture committed to the repository. That fixture contains the raw body string, its X-Hub-Signature-256 value, the X-GitHub-Event header, and the X-GitHub-Delivery GUID. Saving only parsed JSON discards the byte-exact verification input. Capture ends when the delivery becomes a reusable artifact.
Constructing correctly signed fixtures without a live GitHub connection
Captured deliveries show what real events look like, but a fixture library also needs variants with changes made for the test. Programmatic construction removes the need to trigger another GitHub event for every branch or action the handler supports. The order is essential. The generator constructs the body first and then signs precisely that body, producing a request that can be saved and injected later.
The webhooks.cc SDK exposes this through client.sendTo() with a GitHub provider, a push template, and process.env.GITHUB_WEBHOOK_SECRET as the secret. Its push template includes the ref, before and after SHAs, commits array, repository, and sender, with a computed signature header. Calling client.buildRequest() with the same options returns the URL, method, headers, and body without sending the request. The available templates are push, pull_request.opened, and ping. This separates fixture construction from delivery.
A test that implements the same mistaken signing interpretation on both sides can pass while production verification fails. Representative captured deliveries help anchor the generated cases. Useful variants include a protected-branch push, a closed pull request with merged set to either true or false, and a ping. An unrecognized event header and a signature made wrong on purpose also test paths that successful deliveries cannot reach.
Implementing HMAC-SHA256 verification correctly in the handler
On the receiving side, middleware ordering is often more brittle than the HMAC calculation. The webhook route must read the raw body before a JSON parser changes its representation. It then computes HMAC-SHA256 using the webhook secret and compares the result with X-Hub-Signature-256 using constant-time comparison. Only after successful verification does it parse JSON and run business logic.
A raw body parser scoped to the webhook route preserves that order while leaving the global JSON parser available for other routes. Because this order matters, the test needs to go through the HTTP entry point as well as the verification function. Constant-time comparison is required to avoid timing leakage from ordinary string equality checks. A valid fixture should pass through this route unchanged, while a body that has been changed or a wrong signature should fail.
Successful authentication does not establish that a delivery is new. Because the signature has no signed timestamp, the handler needs an idempotency store keyed on X-GitHub-Delivery. A duplicate delivery returns 200 without repeating the work. Tests must check both verification and deduplication, because a valid signature does not give the handler permission to repeat side effects.
Injecting payloads into the handler as first-class CI test inputs
The core CI test starts the application and its backing database and queue in containers. It then sends an HTTP POST directly to the application’s local port using a committed fixture. No tunnel or GitHub connection is involved. The request enters through the actual webhook endpoint, allowing the test to exercise middleware, verification, event routing, and business logic together.
The request body must stay byte-exact as it passes through these steps. Sending the fixture as a raw string preserves the relationship between its contents and its pre-computed signature header. If the test framework serializes the body instead, the signature must be recomputed against that serialized form. Otherwise, the test measures an accidental transformation in the test client rather than the handler’s treatment of the saved delivery. Headers and body form one test input.
The assertion then follows the request beyond its HTTP response. A 200 response does not prove that a record was created, a job was enqueued, or a status was updated correctly. The test must check the state of the database or queue after the request. This makes the integration boundary explicit, from fixture source through HTTP POST and handler execution to a state assertion. The observable effect is the evidence of successful processing.
The first request should return 200 and create the expected record. The second should also return 200 without creating another record or doing the downstream work again.
Negative cases complete the injection pattern. A tampered body or wrong signature must be rejected without the intended business-state change. An event type the handler does not process should receive a graceful 200 response. Because each case is a committed input, CI can repeat it without arranging a corresponding live GitHub event.
How to test multi-step GitHub workflows against a stateful API
A fixture alone is insufficient when the handler calls back into GitHub to post a status check, label a pull request, or update a deployment. The incoming delivery triggers the workflow, but correctness also depends on what subsequent API calls do. Order becomes part of the contract. A simulator must remember what earlier operations did and use that state in its responses.
A stateless mock that always returns 200 cannot establish that a deployment existed before its status was updated. It also cannot reflect that a label was already added during an earlier handler run. A stateful simulator records a created deployment, validates its ID when a status is posted, and returns the updated state when the deployment is requested again.
In CI, the simulator runs beside the application. The test injects the webhook fixture, then checks both the handler’s response and the state recorded from its GitHub API calls. With realistic repository, pull request, and commit records already in place, those calls have resource IDs to work with and each run needs little setup. This keeps the test focused on the handler’s workflow rather than on constructing an empty API world.
The same sequence supports controlled failure tests. The simulator can return a 429 or 503 on a specific API call, allowing the test to inspect retries or graceful degradation. No live credentials or rate-limit consumption are required. Unlike a live dependency, the simulator makes the failure’s position within the workflow repeatable.
Assembling the complete CI pipeline for GitHub webhook testing
The complete pipeline begins by starting the application, backing services, and GitHub API simulator, then waiting for their health checks. Fixture injection follows only when that environment is ready. For each saved request, the test posts the raw body with its pre-computed signature and event headers. It checks that the response is what the test expects when processing succeeds or there are bad signatures, unknown events, or duplicate deliveries. Queries to the database and the simulator’s recorded call log show whether the downstream effects match those responses.
The idempotency pass then posts the fixtures again with the same delivery GUIDs and checks whether records or simulator calls have been duplicated. A fault-injection run configures a critical GitHub API call to return 429 or 503 and exercises the handler’s error path. These tests expose different defects. Middleware-ordering failures break signature verification, duplicate-processing failures repeat effects, and simulated API failures exercise retry and backoff logic. The pipeline controls their inputs and when they fail, without having to wait for external events.
That control does not make the fixtures self-updating. When GitHub announces a schema change or a new event type, the maintenance sequence is to update the fixture first, observe the failing CI test, and fix the handler until it passes. Production failures use the same discipline, preserving the original raw bytes. Each new failure can become a repeatable test, so the pipeline grows more useful without becoming more dependent on live events.


