Webhook Verification Quickstart Prompt Template

This prompt is designed for integration engineers and DevRel teams who need to document the receiver-side contract of a webhook integration. Unlike a typical API quickstart where the user makes an outbound request, this workflow guides a developer through the process of exposing a public HTTP endpoint, accepting an inbound POST request, and cryptographically verifying that the request genuinely originated from your platform. The core job-to-be-done is to minimize the time-to-first-successful-verification, ensuring the developer can confidently distinguish a legitimate event from a spoofed or replayed one before they ever parse the payload. The ideal user is a backend developer who controls a server or serverless function and needs to integrate with your event-driven platform.

Use this prompt when your documentation must cover the full lifecycle of a webhook receiver: standing up an endpoint, extracting and comparing an HMAC signature (typically from a header like X-Signature-256), handling the raw request body correctly for hash computation, and returning the precise HTTP status code (usually 200 OK) that your platform expects to acknowledge delivery. The prompt is particularly effective when you need to generate a guide that includes a runnable code sample, explicit security checks against timing attacks, and a troubleshooting section for common first-time integration mistakes like forgetting to use the raw body or misconfiguring the secret. It is not suitable for generating documentation on how to send webhooks from your platform, nor is it a replacement for an API reference on the webhook payload schema itself.

Before using this prompt, ensure you have a clear specification of the webhook's security contract: the exact header name for the signature, the hashing algorithm (e.g., sha256), the secret format, and the expected acknowledgment response. Do not use this prompt if the integration relies solely on static IP allowlisting or basic authentication tokens without a signature verification step, as the generated output will focus on cryptographic validation patterns that would be irrelevant. After generating the quickstart, you must validate the code sample against your actual webhook sender to confirm the signature computation is correct and that the guide doesn't introduce subtle security flaws like using a non-constant-time comparison function.

This prompt template generates a complete quickstart guide focused exclusively on receiving and verifying webhooks. Unlike API-call quickstarts, this guide must cover endpoint exposure, signature verification, payload parsing, and acknowledgment responses. The template is designed to be copied directly into your AI harness—replace each square-bracket placeholder with your API's specific details before execution. The output should produce a guide that takes a developer from zero to successfully receiving and validating their first webhook event.

textCopy
You are a technical documentation engineer writing a webhook verification quickstart guide for developers integrating with [API_PRODUCT_NAME].

Generate a complete quickstart guide that teaches a developer how to receive, verify, and acknowledge webhooks from [API_PRODUCT_NAME]. The guide must cover:

1. Prerequisites: what the developer needs before starting (a public endpoint URL, a way to inspect incoming requests, the webhook secret from the [DASHBOARD_NAME] dashboard).
2. Endpoint exposure: how to make a local endpoint publicly reachable for testing (recommend [TUNNELING_TOOL] with exact commands).
3. Webhook registration: how to register the endpoint URL in the [DASHBOARD_NAME] dashboard at [REGISTRATION_PATH].
4. Signature verification: how to validate the [SIGNATURE_HEADER_NAME] header using the shared secret and [SIGNING_ALGORITHM] algorithm. Include a complete code example in [PRIMARY_LANGUAGE] that:
   - Reads the raw request body.
   - Computes the expected signature.
   - Compares it to the received signature using a constant-time comparison.
   - Rejects the request with HTTP [REJECTION_STATUS_CODE] if verification fails.
5. Payload parsing: how to parse the verified JSON body, showing the structure of the [EVENT_TYPE_FIELD] field and the [PAYLOAD_DATA_FIELD] object.
6. Acknowledgment response: how to return a [SUCCESS_STATUS_CODE] response immediately after verification, before processing the event, to prevent retries. Include the exact response body shape: [ACKNOWLEDGMENT_BODY_SCHEMA].
7. Idempotency handling: how to use the [IDEMPOTENCY_KEY_FIELD] to detect and ignore duplicate deliveries.
8. Testing: how to trigger a test webhook from the [DASHBOARD_NAME] dashboard at [TEST_TRIGGER_PATH] and confirm successful receipt.
9. Common mistakes: a table of the top 3-5 first-time errors with symptoms, causes, and fixes (cover signature mismatch, body parsing before verification, slow acknowledgment, and missing idempotency handling).

[CONSTRAINTS]
- Every command must be copy-pasteable.
- Every code example must handle errors explicitly.
- Never log or display the webhook secret in examples.
- Use [PRIMARY_LANGUAGE] for all code samples.
- The guide must work for a developer on [TARGET_OS].
- Include exact HTTP status codes and header names.

[OUTPUT_SCHEMA]
{
  "title": "string",
  "time_to_complete": "string (e.g., '10 minutes')",
  "prerequisites": ["string"],
  "steps": [
    {
      "step_number": "number",
      "heading": "string",
      "description": "string",
      "code_block": "string or null",
      "expected_output": "string or null",
      "verification_check": "string"
    }
  ],
  "common_mistakes": [
    {
      "symptom": "string",
      "cause": "string",
      "fix": "string"
    }
  ],
  "next_steps": ["string"]
}

[RISK_LEVEL]
This guide covers signature verification, which is a security-critical operation. Every code example must use constant-time comparison for signature validation. Flag any deviation from this requirement as a security vulnerability.

To adapt this template, replace each square-bracket placeholder with your API's concrete values. The [PRIMARY_LANGUAGE] placeholder should reflect the language most of your integrators use—typically Python, JavaScript, or Go. The [SIGNING_ALGORITHM] placeholder must specify the exact algorithm (e.g., HMAC-SHA256) and the [SIGNATURE_HEADER_NAME] must match your webhook delivery headers exactly. Before shipping the generated guide, validate that every code sample runs successfully against your test environment and that the signature verification step rejects intentionally malformed payloads. For production use, always run the generated guide through a security review to confirm no secrets are exposed and constant-time comparison is correctly implemented.

The webhook verification quickstart prompt is designed to be called programmatically within a documentation generation pipeline, not as a one-off chat interaction. The primary integration point is a CI/CD step that triggers whenever a new webhook event type is added to the platform's API specification or event catalog. The application layer should fetch the event schema, example payload, and signing secret format from the canonical source of truth—typically an OpenAPI spec, an event registry, or a protobuf definition—and inject them into the prompt's [EVENT_SCHEMA], [SIGNING_ALGORITHM], and [EXAMPLE_PAYLOAD] placeholders. This ensures the generated quickstart stays synchronized with the live implementation rather than drifting into stale documentation.

Before calling the model, the harness must validate that all required inputs are non-empty and well-formed: the event schema must be a valid JSON Schema or equivalent structure, the signing algorithm must be one of a known set (e.g., hmac-sha256, rsa-sha256), and the example payload must parse as valid JSON. If any input fails validation, the pipeline should abort with a clear error message rather than generating an incomplete quickstart. After the model returns its output, a post-generation validator should check that the response contains all required sections—endpoint exposure, signature verification code, payload parsing, acknowledgment response, and idempotency guidance—using a structured checklist. Missing sections should trigger a retry with a more explicit instruction appended to the prompt, such as 'The previous response was missing the idempotency handling section. Please include it.'

For model choice, a mid-tier model with strong code generation and instruction-following capabilities (such as Claude 3.5 Sonnet or GPT-4o) is sufficient for this structured generation task. The output should be parsed as structured JSON using the [OUTPUT_SCHEMA] defined in the prompt template, which separates each quickstart section into a typed field. This structured output enables downstream rendering into HTML, MDX, or a documentation platform's component system. Logging should capture the prompt version, model used, input hashes, and validation results for auditability. Because webhook verification is a security-sensitive workflow, any generated quickstart must pass through a human review gate before publication—the harness should flag the output for review and block automated deployment until a technical writer or security engineer approves the signature verification code and security warnings. The most common production failure mode is the model generating a verification example with a hardcoded secret or an insecure comparison operator; the review step is the primary defense against this.