# PlatPhorm Webhook Lab

WebhookLab is the PlatPhorm News event delivery laboratory for https://webhooks.platphormnews.com.

Purpose:
Turn events into reliable, testable, traceable integrations.

Core lifecycle:
1. Define event type: Name the event, version it, and wrap it in the PlatPhorm event envelope. Evidence: eventId. Access: public-safe.
2. Define event contract: Attach JSON Schema or an AsyncAPI-compatible event contract before delivery. Evidence: contractId. Access: public-safe.
3. Register endpoint: Validate endpoint URLs with SSRF protection; server persistence is protected. Evidence: endpointId. Access: protected.
4. Generate payload: Create a positive sample, negative sample, or local event payload from a template. Evidence: payloadHash. Access: public-safe.
5. Sign payload: Build the canonical string and HMAC header without storing the raw secret. Evidence: signatureStatus. Access: public-safe.
6. Send event: Protected sends create an event, delivery, async job, attempt, and trace-linked evidence. Evidence: deliveryId. Access: protected.
7. Receive delivery: Inbound receivers validate signatures where configured and redact payload evidence. Evidence: attemptCount. Access: protected.
8. Inspect attempts: Review status, latency, retry decision, redacted request/response summaries, and trace span. Evidence: responseStatus. Access: public-safe.
9. Retry or replay: Replay and cancel require confirmation plus PLATPHORM_API_KEY unless local-only dry run is selected. Evidence: nextRetryAt. Access: protected.
10. Generate evidence: Package public-safe evidence for Spec, Evals, Sandbox, AgentUI, Monitor, Trace, MCP, API, Docs, Sheets, Catalog, CLI, and Decks. Evidence: evidenceArtifacts. Access: degraded.

Public-safe routes:
- /, /lab, /simulator, /dashboard, /docs, /status, /capabilities
- /endpoints, /events, /deliveries, /replays, /contracts, /signatures, /templates, /integrations, /clients/cli, /faq
- /api/health, /api/v1/health, /api/capabilities, /api/docs, /api/openapi.json, /openapi.yaml, /openapi.json, /api/mcp
- /llms.txt, /llms-full.txt, /llms-index.json, /sitemap.xml, /sitemap-main.xml, /sitemap-index.xml, /rss.xml, /feed.xml, /robots.txt
- /.well-known/mcp.json, /.well-known/agents.json, /.well-known/agent-policy.json, /.well-known/ai-policy.json, /.well-known/trust.json, /.well-known/security.txt

Protected actions require PLATPHORM_API_KEY:
- persistent endpoint registration, update, and deletion
- persistent event creation that sends to registered endpoints
- third-party delivery attempts, replay, cancel, retry, and async delivery job mutation
- contract create, update, delete, persistent test runs, and protected handoffs to Spec, Evals, Sandbox, AgentUI, Monitor, Docs, Sheets, and Decks
- raw delivery details, raw request headers, private payloads, private traces, private audits, registry mutation, and report publishing

Public-safe access:
- homepage, docs, FAQ, OpenAPI, llms, RSS, sitemap, robots, and well-known policy files
- Lab shell, local-only payload generation, public templates, JSON/schema validation, and transient signature utilities
- redacted event, endpoint, delivery, contract, integration, health, and route-compliance summaries when storage is available
- read-only MCP introspection and public-safe MCP tools

Safety model:
- public smoke tests are read-only or local/demo-only
- raw signing secrets are never persisted, returned, logged, or placed in URLs
- endpoint registration and delivery use SSRF protection
- Authorization, cookies, platform credential values, signing secrets, provider keys, database URLs, passwords, private keys, and secret-like values are redacted
- raw x-vercel-ja4-digest is never exposed in UI, RSS, sitemap, llms, OpenAPI examples, logs, public traces, or public artifacts

Machine-readable metadata:
- Capabilities: https://webhooks.platphormnews.com/api/capabilities
- PlatPhorm manifest: https://webhooks.platphormnews.com/.well-known/platphorm.json
- OpenAPI: https://webhooks.platphormnews.com/api/docs
- MCP: https://webhooks.platphormnews.com/api/mcp

Core capabilities:
- Webhook Simulation: Generate webhook event payloads and run public-safe local simulations without persistent delivery. (public-safe)
- Signature Generation: Generate HMAC signatures for test webhook payloads without persisting raw secrets. (public-safe)
- Signature Verification: Verify webhook signatures against payloads and timestamp tolerance without persisting raw secrets. (public-safe)
- Endpoint Registration: Register webhook receiver endpoints with SSRF-safe URL validation. (protected, protected operations available)
- Event Creation and Listing: Create persistent webhook events with protected dispatch; public reads are redacted. (public-safe, protected operations available)
- Delivery Tracking: Inspect webhook delivery and attempt state with public-safe redaction. (public-safe)
- Delivery Replay: Replay webhook deliveries with protected authorization and explicit operator confirmation. (protected, protected operations available)
- Contract Creation: Create and manage persistent webhook contracts. (protected, protected operations available)
- Payload Validation: Validate webhook payloads against known contracts or demo schemas. (public-safe)
- Vercel Webhook Receiver: Receive Vercel webhook events and verify configured Vercel signatures. (protected, protected operations available)
- MCP Integration: Expose webhook tools, resources, and prompts through JSON-RPC MCP. (public-safe)
- Agent Endpoint: Expose safe agent actions with protected mutations gated by PLATPHORM_API_KEY. (public-safe, protected operations available)
- Docs and OpenAPI: Publish human API docs and parseable OpenAPI metadata for public and protected routes. (public-safe)
- llms, Sitemap, Robots, Feed: Expose public-safe discovery files for agents and crawlers. (public-safe)

Toolchain integrations:
- Spec Workbench: Validate webhook contracts and generate schema reports. Status: degraded. Access: protected.
- Evals: Create contract suites and score retry, replay, and delivery behavior. Status: degraded. Access: protected.
- Sandbox: Generate receiver tests and validate sample payload handling in a safe runtime. Status: degraded. Access: protected.
- AgentUI: Generate payload forms, contract editors, and protected replay panels. Status: degraded. Access: protected.
- Monitor: Publish delivery health, endpoint health, and webhook failure-rate summaries. Status: degraded. Access: protected.
- Trace: Link events, deliveries, attempts, replays, and contract tests to trace timelines. Status: degraded. Access: public-safe.
- MCP Gateway: Expose WebhookLab tools, resources, prompts, schema validation, and tool status. Status: working. Access: public-safe.
- API Hub: Register OpenAPI, event contracts, webhook metadata, and API product descriptors. Status: degraded. Access: protected.
- Docs: Publish delivery reports, contract remediation notes, and incident docs. Status: degraded. Access: protected.
- Sheets: Export delivery matrices and endpoint health reports. Status: degraded. Access: protected.
- Decks: Generate executive delivery evidence summaries. Status: degraded. Access: protected.
- platphormctl: Run repeatable webhook tests, MCP validation, site inspection, and policy checks. Status: working. Access: public-safe.

platphormctl examples:
- platphormctl site inspect webhooks
- platphormctl mcp validate webhooks
- platphormctl policy inspect webhooks
- platphormctl webhooks events
- platphormctl webhooks endpoints
- platphormctl webhooks send --event webhook.test --payload payload.json --dry-run
- platphormctl webhooks verify-signature --payload payload.json --signature <sig>
- platphormctl webhooks validate-contract --contract contract.json --payload payload.json

Recommended agent commands:
- npx @platphormnews/platphormctl site inspect https://webhooks.platphormnews.com --json --trace
- npx @platphormnews/platphormctl site routes https://webhooks.platphormnews.com --json --trace
- npx @platphormnews/platphormctl site openapi https://webhooks.platphormnews.com --json --trace
- npx @platphormnews/platphormctl site llms https://webhooks.platphormnews.com --json --trace
- npx @platphormnews/platphormctl site sitemap https://webhooks.platphormnews.com --json --trace
- npx @platphormnews/platphormctl mcp initialize https://webhooks.platphormnews.com/api/mcp --json --trace
- npx @platphormnews/platphormctl mcp tools https://webhooks.platphormnews.com/api/mcp --json --trace
- npx @platphormnews/platphormctl --include webhooks.platphormnews.com network validate --best-effort --evidence --json --trace