validate_webhook_handler
Check webhook handler design for PayRetailers compliance: catches ack-after-processing timeouts, 500 on business errors, missing eventId dedup, and signature flaws. Returns actionable errors, warnings, and info.
Instructions
REQUIRED whenever the user is designing, describing, or about to code a webhook receiver for PayRetailers — even if the design looks fine. Analyses a declarative description of the handler (URL, processing mode, ack strategy, idempotency, signature verification, replay protection, error mapping, ordering assumptions) against the PayRetailers contract and returns {errors, warnings, info} with actionable codes. Catches the top failure modes: acknowledging AFTER processing (times out and gets retried), returning 500 on business errors (infinite retries), missing eventId de-duplication (double-fulfilment), assuming wall-clock order (state corruption), HTTPS missing, signature disabled in production, replay window absent. Pair with get_webhook_playbook when designing from scratch.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | The public URL that will receive PayRetailers webhook POSTs. | |
| ordering | No | Whether the handler relies on wall-clock order of events for the same entityId. Real deliveries can arrive out-of-order; a handler that assumes order will corrupt state. | |
| ackStrategy | Yes | When the handler returns 200: 'before-processing' (recommended), 'after-processing' (blocks retries but risks timeouts), 'conditional-on-outcome' (dangerous: business errors trigger retries). | |
| environment | No | Deployment target for this handler. Defaults to 'sandbox'. | |
| ipAllowlist | No | Optional IP allowlist. NOT sufficient by itself — always combine with signature verification. | |
| errorHandling | No | How the handler maps internal exceptions to HTTP status. Business errors ('order not found') should NOT return 500 — that triggers infinite retries. | |
| processingMode | Yes | How the handler processes the event: 'sync-in-request' = all business logic runs before returning 200; 'async-queue' = enqueue and return 200 immediately (recommended); 'async-thread' = fire-and-forget in-process background thread. | |
| languageOrStack | No | Optional stack hint (e.g. 'C# ASP.NET 8', 'Node.js Express', 'Python FastAPI'). Only used to sharpen suggestions. | |
| replayProtection | No | Optional replay protection based on eventDate. Recommended: enabled=true with maxAgeMinutes=5. | |
| idempotencyStrategy | Yes | How duplicate deliveries are de-duplicated. 'by-eventId' is the required strategy. | |
| signatureVerification | Yes | How the handler treats the PayRetailers webhook signature. 'strict' = reject on mismatch (recommended); 'log-only' = log and continue; 'disabled' = no verification (only acceptable for sandbox). | |
| idempotencyStoreTtlDays | No | How long processed eventIds are retained. Recommended >= 30 days to survive replay attempts and backlogs. | |
| responseTargetLatencyMs | No | Expected p95 latency of your endpoint in milliseconds. PayRetailers targets < 3000 ms for the 200 ack. |