Webhook Payload Builder — Construct & Validate Webhook Payloads

Building webhook payloads by hand is tedious and error-prone. A missing field, a wrong type, or an invalid JSON structure will cause silent failures that are difficult to debug in production. The Webhook Payload Builder gives you a visual editor with real-time JSON validation, provider-specific templates, a header constructor, and an HMAC signature calculator — everything you need to construct, validate, and test webhook payloads from your browser.

Select a template for GitHub, Stripe, Slack, or Discord to start with a valid payload structure. Customize fields, add headers, compute the HMAC-SHA256 signature, and copy the generated cURL command to send the webhook to any endpoint. The validator checks for structural errors, type mismatches, and missing required fields before you send a single byte.

Understanding Webhook Payload Construction

A webhook payload is the structured data transmitted in an HTTP request body when an event occurs in a source system. When Stripe processes a payment, when GitHub receives a push, or when a Slack workflow triggers, the originating system constructs a payload describing the event and sends it to a pre-configured URL. The payload carries the essential context that the receiving system needs to react — event type, affected resources, timestamps, and metadata.

Getting the payload right matters. A malformed payload will be rejected by the receiving endpoint. A payload with missing fields will cause downstream logic to fail. A payload without a valid signature will be discarded by any properly-secured webhook handler. The Webhook Payload Builder addresses each of these failure modes by providing a structured editing environment with real-time validation and signature generation.

JSON Schema Validation for Webhook Payloads

JSON Schema is the standard mechanism for defining the structure of a JSON document. In the context of webhooks, schema validation ensures that every required field is present, every value has the correct type, and the overall structure matches what the receiving endpoint expects. Without schema validation, subtle errors like a string where a number is expected or a missing nested object can pass through undetected until they cause a runtime crash.

The validation engine in this tool checks several layers of correctness. First, it verifies that the payload is syntactically valid JSON — matching braces, proper quoting, correct comma placement. Second, it checks for common structural patterns specific to each provider template. For GitHub push events, it verifies the presence of ref, repository, pusher, and commits fields. For Stripe events, it checks for id, type, data.object, and created timestamp. Each validation error includes the specific field path and a human-readable explanation.

Schema validation is not just a development convenience — it is a production safety mechanism. Webhook handlers that skip validation are vulnerable to unexpected payloads from provider API changes, version upgrades, and edge cases that documentation does not cover. Building validation into your payload construction workflow catches these issues before they reach production.

The Anatomy of Webhook Payloads by Provider

GitHub Webhooks follow a consistent structure across all event types. Every payload includes a top-level action or event-specific identifier, a repository object with full repository metadata, and a sender object identifying the user who triggered the event. Push events include a commits array with individual commit details. GitHub sends the event type in the X-GitHub-Event header and the signature in X-Hub-Signature-256.

Stripe Webhooks use an Event object wrapper. Every payload contains id (the event ID), type (like payment_intent.succeeded), data.object (the affected resource), and created (Unix timestamp). The signature is sent in the Stripe-Signature header with a format of t=timestamp,v1=signature. Stripe requires signature verification using the timestamp to prevent replay attacks.

Slack Incoming Webhooks accept a payload with text for simple messages or blocks for rich formatting using Block Kit. Slack also supports attachments (legacy) and unfurl_links control. Unlike GitHub and Stripe, Slack incoming webhooks do not include a signature header — security relies on keeping the webhook URL secret.

Discord Webhooks use a similar structure to Slack but with different field names. The payload accepts content for plain text and embeds for rich content with titles, descriptions, colors, and fields. Discord webhooks also support username and avatar_url overrides to customize the sender appearance.

HMAC Signature Verification Deep Dive

HMAC (Hash-based Message Authentication Code) is the cryptographic mechanism that webhook providers use to prove payload authenticity. The sender computes HMAC by hashing the raw request body with a shared secret key, then includes the resulting hash in a request header. The receiver performs the same computation and compares results. If they match, the payload was sent by someone who knows the secret and was not modified in transit.

The most common mistake in HMAC verification is using a parsed and re-serialized body instead of the raw bytes. When a web framework parses JSON and you serialize it back to a string, whitespace and key ordering may change. Even a single extra space invalidates the signature. In Express.js, use express.raw({ type: 'application/json' }) on your webhook route. In Python Flask, use request.get_data() instead of request.json.

Timing attacks are another subtle vulnerability. Comparing signatures using === or == in JavaScript leaks information through execution time differences. Use crypto.timingSafeEqual() in Node.js or hmac.compare_digest() in Python to perform constant-time comparison. This tool uses the Web Crypto API for HMAC computation, which provides the same cryptographic primitives available server-side.

Building Custom Headers for Webhook Requests

Headers carry metadata that is essential for webhook processing. The Content-Type header tells the receiver how to parse the body — almost always application/json for modern webhooks. The signature header varies by provider: X-Hub-Signature-256 for GitHub, Stripe-Signature for Stripe, X-Shopify-Hmac-SHA256 for Shopify. Custom headers like X-Request-ID provide idempotency keys for deduplication.

When building webhook integrations, include a unique event ID header so the receiver can detect and skip duplicate deliveries. Include a timestamp header to enable replay attack prevention. Some providers also include a User-Agent header identifying the sender, which is useful for logging and access control. The header builder in this tool lets you add any combination of standard and custom headers.

Payload Size and Performance Considerations

Webhook payloads should be as small as possible while still containing the information needed for the receiver to act. Most providers impose size limits — GitHub limits payloads to 25 MB, Stripe to around 64 KB for most events, and Slack to 40 KB per message. Exceeding these limits causes silent failures or truncation.

A common pattern is to send a lightweight notification payload containing only the event type, resource ID, and timestamp, then have the receiver fetch the full resource data via API call. This approach keeps payloads small, avoids data staleness (the API call returns the current state), and reduces the volume of sensitive data transmitted via webhooks. The trade-off is an additional API call per event, which adds latency and requires API authentication on the receiver side.

Testing Webhook Payloads in Development

Before sending a webhook payload to a production endpoint, test it against a local development server. Use this builder to construct the payload, validate its structure, and generate the cURL command. Then use a tunneling tool like ngrok or Cloudflare Tunnel to expose your local server to the internet, or use InvokeBot's request builder to send the payload directly.

For systematic testing, save a library of known-good payloads for each event type you handle. Use these as fixtures in your automated test suite. The template library in this tool provides a starting point for GitHub, Stripe, Slack, and Discord payloads. Customize them with your test data, then export the JSON for use in unit tests, integration tests, and CI/CD pipelines.

Webhook testing should cover four scenarios: valid payload with correct signature, valid payload with incorrect signature (should be rejected), malformed payload (should return 400), and duplicate payload with the same event ID (should be idempotent). Each scenario tests a different layer of your webhook handler. Teams building secure webhook endpoints should also test for replay attacks by sending a valid signature with an expired timestamp.

Common Payload Construction Errors

The most frequent errors when constructing webhook payloads are missing required fields, incorrect data types, invalid JSON syntax, and wrong content types. A missing type field in a Stripe event will cause the handler to crash. An integer where a string is expected will pass JSON parsing but fail validation. A trailing comma in JSON (valid in JavaScript but not in JSON) causes a parse error. Setting Content-Type: text/plain instead of application/json causes the body to be interpreted as a raw string.

This tool addresses each of these errors with real-time feedback. As you type, the validator highlights syntax errors with line numbers. When you click Validate, the schema checker reports missing fields and type mismatches. The template library ensures you start with a structurally valid payload, reducing the chance of fundamental errors. For teams managing complex JSON structures, the visual editor is significantly more reliable than hand-editing raw JSON in a text editor.