Webhook Signature Verification Test Prompt Template

This prompt is for integration engineers and security-minded QA testers who need to validate that a webhook receiver correctly verifies cryptographic signatures, rejects expired or replayed payloads, and returns clear error responses. The job-to-be-done is generating a structured, repeatable test suite that covers the full lifecycle of signature verification: valid signatures, tampered payloads, expired timestamps, replay attempts, malformed headers, and edge cases like missing signature schemes. The ideal user already has access to the webhook provider's signing secret, the expected signature algorithm (e.g., HMAC-SHA256), and the endpoint's documented behavior for success and failure responses.

Do not use this prompt when you need to test the webhook sender's signing implementation, when you are load-testing webhook throughput, or when the receiver's verification logic is not yet implemented. This prompt assumes the receiver exists and produces observable HTTP responses. It is not a substitute for penetration testing or a full cryptographic audit. If the webhook receiver handles payment events, PII, or account state changes, you must pair the generated test cases with human review and run them in a staging environment before production use. The prompt works best when you provide the exact signature header format, the timestamp tolerance window, and any replay prevention mechanism in use.

After reading this section, you should have a clear picture of whether your testing context matches the prompt's design. Next, copy the prompt template, fill in your webhook's specific parameters, and run it against your receiver. Pay close attention to the eval criteria section—it defines what a passing test looks like and where cryptographic verification tests commonly produce false positives or miss subtle failures.

This prompt template is designed to produce structured test cases that validate webhook signature verification logic. It covers timestamp tolerance checks, signature computation correctness, replay prevention, and malformed payload rejection. The template uses square-bracket placeholders so you can swap in your specific webhook provider's signing algorithm, header conventions, and security requirements before feeding it into a model or an automated test generation pipeline.

codeCopy
You are a test engineer designing webhook signature verification tests.

Generate a set of test cases for a webhook endpoint that verifies signatures using the following configuration:

[WEBHOOK_PROVIDER_DETAILS]
- Signing algorithm: [SIGNING_ALGORITHM]
- Signature header name: [SIGNATURE_HEADER_NAME]
- Timestamp header name: [TIMESTAMP_HEADER_NAME]
- Timestamp tolerance (seconds): [TIMESTAMP_TOLERANCE]
- Secret key format: [SECRET_KEY_FORMAT]
- Payload format: [PAYLOAD_FORMAT]

[ENDPOINT_BEHAVIOR]
- Expected success response: [SUCCESS_RESPONSE]
- Expected failure response: [FAILURE_RESPONSE]
- Replay prevention mechanism: [REPLAY_PREVENTION]

[OUTPUT_SCHEMA]
Return a JSON array of test case objects with the following structure:
{
  "test_cases": [
    {
      "id": "string",
      "name": "string",
      "category": "signature_valid | signature_invalid | timestamp_valid | timestamp_expired | timestamp_future | replay_detection | malformed_payload | missing_header | algorithm_mismatch",
      "description": "string",
      "preconditions": ["string"],
      "input": {
        "headers": {},
        "payload": {},
        "secret": "string"
      },
      "expected_result": {
        "status_code": 0,
        "body_contains": ["string"],
        "body_not_contains": ["string"]
      },
      "signature_generation_instructions": "string"
    }
  ]
}

[CONSTRAINTS]
- Generate at least [MIN_TEST_CASES] test cases covering all categories.
- Include both positive cases (valid signatures within tolerance) and negative cases (expired, tampered, replayed, malformed).
- For each negative case, explain what makes the signature invalid.
- Include edge cases: exactly at timestamp boundary, empty payload, maximum payload size, unicode payloads.
- Do not include test cases that depend on network conditions or external services.
- Signature generation instructions must be precise enough for a developer to implement without guessing.

[EXAMPLES]
Example test case:
{
  "id": "sig-001",
  "name": "Valid signature within timestamp tolerance",
  "category": "signature_valid",
  "description": "A correctly signed payload with a timestamp 30 seconds in the past should be accepted when tolerance is 300 seconds.",
  "preconditions": ["Secret key is configured on the server", "Server clock is synchronized"],
  "input": {
    "headers": {
      "X-Signature": "t=1690000000,v1=abc123...",
      "Content-Type": "application/json"
    },
    "payload": {"event": "order.created", "id": "ord_123"},
    "secret": "whsec_test_secret"
  },
  "expected_result": {
    "status_code": 200,
    "body_contains": ["received"],
    "body_not_contains": ["invalid", "error"]
  },
  "signature_generation_instructions": "Compute HMAC-SHA256 of '<timestamp>.<payload_string>' using the secret key, then format as 't=<timestamp>,v1=<hex_digest>'"
}

[RISK_LEVEL]
This is a security-critical test suite. Cryptographic verification failures can lead to unauthorized webhook processing. All generated test cases must be reviewed by a security engineer before inclusion in a test suite. Pay special attention to timing side-channel considerations and constant-time comparison requirements.

After copying this template, replace each square-bracket placeholder with your webhook provider's specific configuration. For common providers like Stripe, GitHub, or Shopify, fill in their documented signing algorithms and header conventions. If your system uses a custom signing scheme, provide enough detail in [WEBHOOK_PROVIDER_DETAILS] that the model can derive correct signature computation steps. The [OUTPUT_SCHEMA] section is already structured for direct ingestion into a test runner—adjust the field names only if your test framework requires a different shape. Always run the generated test cases through a security review before executing them against a live endpoint, since incorrect signature verification tests can mask real vulnerabilities.

The webhook signature verification prompt is designed to be called programmatically as part of a CI pipeline or on-demand test generation workflow. It expects a structured input payload containing the webhook provider's signature scheme (e.g., HMAC-SHA256, asymmetric RSA), the expected header names, a sample payload, and the secret or public key material. The prompt returns a JSON array of test case objects, each with a unique ID, test description, setup steps, expected behavior, and a pass/fail assertion. You should wrap the prompt call in a thin application layer that validates the output schema before any test case is executed.

Integration pattern: Store the prompt template in a version-controlled prompt registry. At runtime, your test harness assembles the prompt by injecting the provider-specific [SIGNATURE_SCHEME], [HEADER_SPEC], [SAMPLE_PAYLOAD], and [KEY_MATERIAL] placeholders. Send the assembled prompt to your model endpoint (GPT-4o, Claude 3.5 Sonnet, or equivalent) with response_format set to json_object and a JSON Schema constraint that enforces the test_cases array structure. On response, run a strict validator that checks: (1) every test case has a non-empty id, description, and assertion field; (2) cryptographic test cases reference the correct algorithm from the input; (3) replay prevention cases include timestamp manipulation steps; (4) malformed payload cases specify the exact mutation applied. Reject and retry any response that fails validation, appending the validation errors to the next request as [PREVIOUS_ERRORS].

Retry and fallback logic: Implement a maximum of two retries. On the first retry, include the validation failure details. On the second retry, lower the temperature to 0.1 and add an explicit instruction: 'Return only test cases that pass the provided JSON Schema. Do not include commentary.' If the second retry still fails validation, log the raw response, surface it to a human reviewer through your test management system, and fall back to a static set of baseline test cases stored alongside the prompt. For high-risk payment or PII-processing webhooks, require human approval on all generated test cases before they enter the automated execution queue. Log every prompt version, input hash, output, and validation result for auditability.

Execution harness: Once validated, feed each test case into your API test runner (e.g., Jest, pytest, k6). The assertion field should be directly executable—structure it as a code-ready expression like expect(response.status).toBe(401) or assert response.headers['X-Signature-Valid'] == 'false'. For cryptographic verification tests, the harness must compute the expected signature using the same algorithm and key material from the input, then compare against the webhook endpoint's response. Track pass/fail per test case and aggregate results into a signature-verification coverage report. Avoid executing generated test cases against production webhook endpoints without a dedicated test environment and synthetic keys.