Developer & Data · THE NO-PANIC PLAN
Inspect a webhook JSON payload before integration
A webhook payload is external input, even when it appears to come from a familiar service. Use synthetic or redacted sample data to understand event shape, required fields, optional values, and downstream cases. The Nirmion tester processes the pasted sample in your browser, but it cannot authenticate the sender, validate a provider signature, or guarantee that production code handles the event safely. Perform signature verification and schema enforcement in the receiving server using the provider?s current instructions.
MISSION Inspect a representative webhook JSON event against its provider?s documented schema and expected application behavior before writing or changing a receiving integration.
Inspect a webhook sample locallyTHE REAL-WORLD BIT
What happens outside this browser tab?
Identify the provider, event type, API version, and intended receiver; obtain a test or redacted payload from a trusted provider source; parse and inspect the JSON without executing it; compare the event envelope and field types with the provider?s versioned documentation; test representative optional, null, missing, and duplicate-key cases with the local tester; implement server-side signature verification and schema validation separately; then use safe fixtures to test idempotency, retries, acknowledgments, and side effects before production.
YOUR CHECKLIST, WITH FEWER DRAMATIC SIGHES
One step at a time.
Follow the order below. If a step names a Nirmion tool, its link is right there with it.
- 01
Define the provider, event, version, and receiver contract
Write down which provider sends the webhook, the exact event name, documented API or payload version, receiver endpoint, and the business action the event may trigger. Identify which fields your application needs and who owns the integration. Do not assume that two providers use the same event envelope or that a payload example from another API version is interchangeable. Keep verification secrets, authorization headers, and live endpoint URLs out of the notes you plan to share.
- 02
Get a representative sample from a trusted test source
Prefer the provider?s official test event, sandbox, or delivery log for the exact event and version. If you must inspect a production delivery, first remove personal data, credentials, signature headers, and customer-specific identifiers; preserve only the fields needed to test the contract. Save the event type and retrieval date beside the fixture so it is clear which documentation version it represents. Never use a random payload from an untrusted sender as proof of what the provider normally sends.
- 03
Inspect JSON syntax without executing or normalizing the payload
Check that the sample is valid JSON and review object keys, arrays, strings, numeric values, booleans, and nulls in their original context. RFC 8259 says object member names should be unique; parsers can behave unpredictably when duplicate names appear, so resolve duplicates at the source instead of relying on which value a local parser keeps. Do not evaluate the payload as code or run embedded strings as commands. Keep the original fixture unchanged so a parser or formatter cannot conceal a meaningful difference.
- 04
Use the local tester to explore the payload shape
Paste only a synthetic or redacted JSON sample into Webhook Payload Tester. Use the browser-local tool to inspect the envelope, event fields, and example values, then compare its output with the documented receiver contract. Treat its result as a development aid: it does not contact the provider, verify a signature, prove schema compatibility, or test your server. If the payload contains unexpected fields or is too large for safe review, stop and use an approved local development environment with appropriate access controls.
Evidence:OWASP Cheat Sheet ? Webhook Security - 05
Compare required, optional, nullable, and versioned fields
For each field the receiver uses, record whether it is required, optional, nullable, nested, or repeated according to the provider?s documentation. Test cases where optional fields are absent, values are null, arrays are empty, values change type, and unknown fields are added. Compare the event type and version headers separately from the JSON body. A valid JSON document can still be the wrong event, the wrong provider version, or a structurally valid object that omits the business fact your handler requires.
- 06
Keep authenticity and security checks on the receiving server
Before processing a real delivery, implement the provider?s signature verification exactly as documented, using the original request body bytes and the correct secret stored server-side. For GitHub, official guidance uses the X-Hub-Signature-256 HMAC and recommends a constant-time comparison; another provider may use a different scheme. Then enforce your application?s schema and size limits, reject unexpected or malformed input safely, avoid logging full personal payloads or secrets, and ensure untrusted fields cannot become commands, queries, or unsafe output. The browser tester cannot perform these controls.
- 07
Turn the sample into safe integration tests
Create a small fixture set for the documented event, missing optional data, null or empty values, malformed JSON, duplicate keys, and an unknown event version. Run those fixtures through the receiving handler in a test environment and confirm that valid events create the intended result once, invalid or unauthenticated requests cause no side effect, retries do not duplicate work, and the endpoint returns the provider-required acknowledgment within its stated time. Keep fixtures synthetic or redacted and recheck them when the provider changes its event documentation.
THE HELPER CREW
Tools for the fiddly bits.
These are the currently published Nirmion tools matched to this guide. Open a tool page for its accepted inputs and limits.
RECEIPTS, PLEASE
Sources & review notes
Each source is linked to the steps it supports. Open it to check its scope and current guidance.
Source checked 2026-10-10