Webhook Troubleshooting and Debugging Guide Prompt

Identifies the specific webhook provider or platform being debugged to scope the guide.

AcmePay Webhooks

Must be a non-empty string. Validate against an allowlist of supported service names in the application config to prevent hallucinated provider details.

Specifies the consumer's programming language, framework, and runtime to generate relevant code snippets and tool recommendations.

Node.js 20 with Express 4.x, deployed on AWS Lambda

Parse for language and framework tokens. If missing, default to a generic curl/CLI guide. Validate that the stack is in the supported runtimes list before generating platform-specific instructions.

The user-reported problem or observed failure behavior that the guide must diagnose.

Webhooks arrive with valid signatures but return 409 Conflict on every delivery.

Must be a non-empty string. Check for minimum length (>20 chars) to ensure sufficient detail. If null, the prompt should request the symptom before proceeding.

A raw excerpt from the consumer's application logs, webhook dashboard, or error monitoring tool to ground the diagnosis in evidence.

2025-03-15T10:32:01.201Z ERROR webhook-handler: idempotency key collision key=ord_8291 status=CONFLICT

Optional. If provided, validate that it is plain text under 4000 characters. If missing, the guide must instruct the user on which logs to collect. Never allow the model to invent log entries.

Boolean flag indicating whether the consumer has correctly configured webhook signature verification.

Must be true, false, or null. If null, the guide must include a step to verify this. If false, the guide must prioritize signature verification setup before other debugging steps.

Specifies the consumer's idempotency handling strategy or requirement to tailor replay and deduplication guidance.

Database-level unique constraint on event_id column with a 72-hour deduplication window.

Optional. If provided, validate that it describes a concrete mechanism. If missing, the guide must include a section on implementing idempotency as a likely root cause for duplicate or conflicting events.

A structured summary of recent delivery attempts, including timestamps, HTTP status codes, and retry counts, to identify patterns.

Attempt 1: 2025-03-15T10:32:00Z -> 409 Conflict; Attempt 2: 2025-03-15T10:33:00Z -> 409 Conflict; Attempt 3: 2025-03-15T10:35:00Z -> 409 Conflict (max retries exceeded)

Optional. If provided, parse for status codes and timestamps. If missing, the guide must instruct the user to retrieve this from the provider dashboard or their own delivery logs. Validate that timestamps are ISO 8601.

string

Must be a non-empty string under 120 characters. Parse check: reject if empty or exceeds length.

array of objects

Each object must contain 'step_id' (string), 'question' (string), 'yes_path' (string|null), 'no_path' (string|null). Schema check: reject if any required field is missing.

array of objects

Each object must contain 'symptom' (string), 'likely_causes' (array of strings, min 1 item), 'confidence' (string enum: 'high','medium','low'). Schema check: reject if 'likely_causes' is empty or 'confidence' is not in enum.

array of objects

Each object must contain 'log_source' (string), 'fields_to_check' (array of strings), 'expected_values' (object), 'anomaly_indicators' (array of strings). Parse check: reject if 'fields_to_check' is empty.

array of objects

Each object must contain 'tool_name' (string), 'purpose' (string), 'command_example' (string), 'output_interpretation' (string). Null allowed for 'command_example' if tool is GUI-only. Schema check: reject if 'tool_name' or 'purpose' is empty.

array of strings

Must contain at least 3 items. Each string must be under 280 characters. Parse check: reject if fewer than 3 items or any item exceeds length.

array of objects

Each object must contain 'condition' (string), 'action' (string), 'contact_role' (string). Schema check: reject if any required field is missing. Approval required: human review recommended before publishing escalation paths.

object

Must contain 'guide_version' (string, semver format), 'last_updated' (string, ISO 8601 date), 'applies_to_webhook_version' (string). Parse check: reject if 'guide_version' is not valid semver or 'last_updated' is not valid ISO 8601.

Every listed symptom maps to at least one verifiable root cause drawn from the system's actual error catalog or delivery lifecycle.

Symptom describes a generic network error with no specific webhook context, or cause references an event type that does not exist in the system.

Spot-check 3 symptoms against the source [ERROR_CATALOG] and [EVENT_TYPE_CATALOG]. Confirm each cause is a real state in the delivery pipeline.

Every decision node in the flowchart has a clear yes/no condition based on an observable signal (HTTP status code, log entry, header value). No node requires intuition.

A decision node asks 'Is the server working?' without specifying the exact health-check endpoint or expected response code.

Trace one complete path through the flowchart for a known failure scenario. Verify each branch condition can be evaluated by reading a log line or API response.

All suggested diagnostic commands (curl, webhook site tools, CLI) are read-only, include explicit placeholder replacement warnings, and never expose secret keys in example output.

A curl example includes a hardcoded secret in the command or suggests a POST that would mutate production state without a confirmation gate.

Audit every code block for write operations. Confirm all [WEBHOOK_SECRET] placeholders are used and a warning precedes any command that could replay events.

Log inspection steps reference exact field names from the [WEBHOOK_LOG_SCHEMA] (e.g., delivery_attempt.status, signature.validation_error) and explain how to interpret values.

Guidance says 'check the logs for errors' without specifying which log stream, which fields to filter on, or what a healthy log entry looks like.

Verify that at least 3 log field paths match the actual log schema. Confirm the guide explains the difference between a delivery failure and a signature failure in log terms.

The guide recommends at least one method for replaying or inspecting webhook traffic (e.g., request bin, local tunnel, dashboard replay API) with step-by-step setup instructions.

The guide tells the user to 'test with a tool' but does not name a specific tool, provide a setup command, or explain how to route traffic to it.

Execute the setup instructions for the recommended inspection tool in a clean environment. Confirm the tool captures a webhook payload within 5 minutes.

The guide defines a clear boundary where the consumer should stop self-debugging and contact the provider, including the exact information to include in the support request (delivery attempt ID, timestamp, event ID).

The guide ends with 'contact support' without specifying what evidence to collect, or suggests the consumer debug provider-side infrastructure themselves.

Check that the escalation section lists at least 3 required pieces of evidence from the [SUPPORT_TICKET_TEMPLATE] and does not instruct the consumer to inspect provider-internal dashboards.

The guide explicitly warns against at least 3 common consumer mistakes (e.g., blocking the webhook with a WAF, returning 200 before processing, ignoring duplicate events) with concrete detection steps.

Pitfalls are described vaguely ('make sure your server is configured correctly') without a specific check the consumer can run.

For each listed pitfall, verify there is a corresponding diagnostic step in the flowchart or log inspection section that would catch it.

If signature verification is covered, the guide includes steps to debug raw payload access, header extraction, timing issues, and secret mismatch, with language-specific code snippets.

The signature section only says 'check your secret' without explaining how to verify the raw payload body matches what was signed or how to test with a known-good payload.

Run the signature debug steps against a deliberately misconfigured endpoint. Confirm the guide helps identify whether the error is in secret storage, payload encoding, or header parsing.