# PlatPhorm Webhook Lab Full Context

WebhookLab is both a human webhook testing product and an agent-operable PlatPhorm surface. It turns events into reliable, testable, traceable integrations across the PlatPhormNews network.

## 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 contract
- 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

## Protected contract
Persistent writes require Authorization: Bearer $PLATPHORM_API_KEY or X-PlatPhorm-API-Key: $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

## Required trust policy line
Web dashboard, public-safe discovery, browser-based operations, trusted-domain discovery, standard route compliance, Vercel metadata capture, trace inspection, and agentic workflow discovery are intentionally supported for public read-only debugging and operator workflows. Mutating, administrative, ingestion, replay, fork, remediation, deployment, sync, test-triggering, reporting, and write actions require PLATPHORM_API_KEY.

## Safety
- signing secrets are transient for public signature utilities
- raw signing secrets are never persisted or returned
- public examples use demo/test secrets only
- endpoint registration blocks localhost, private IPv4 ranges, IPv6 loopback, link-local hosts, metadata addresses, local DNS helpers, and unsafe schemes
- evidence and responses redact Authorization, cookies, platform credential values, signing secrets, provider keys, database URLs, passwords, private keys, and secret-like values
- public simulator and lab workflows do not send webhook payloads to arbitrary third-party URLs
- raw x-vercel-ja4-digest is captured only as redacted/correlation-safe metadata and is never exposed publicly

## Routes
- https://webhooks.platphormnews.com/: WebhookLab product overview and lifecycle entry point.
- https://webhooks.platphormnews.com/lab: Public-safe webhook lab for payloads, signatures, contracts, and dry-run flows.
- https://webhooks.platphormnews.com/dashboard: Redacted or degraded delivery health dashboard.
- https://webhooks.platphormnews.com/docs: WebhookLab API, MCP, CLI, policy, and safety documentation.
- https://webhooks.platphormnews.com/explore: Capability and lifecycle exploration.
- https://webhooks.platphormnews.com/changelog: Public-safe WebhookLab updates.
- https://webhooks.platphormnews.com/status: Health and route compliance status.
- https://webhooks.platphormnews.com/capabilities: Human-readable route, MCP, OpenAPI, and integration capability harness.
- https://webhooks.platphormnews.com/endpoints: Public-safe endpoint registry shell and protected registration policy.
- https://webhooks.platphormnews.com/events: Redacted event summaries and local event starting points.
- https://webhooks.platphormnews.com/deliveries: Delivery state and attempt inspection shell.
- https://webhooks.platphormnews.com/replays: Protected replay and cancel safety policy.
- https://webhooks.platphormnews.com/contracts: Contract validation and registry shell.
- https://webhooks.platphormnews.com/signatures: HMAC signature generation, verification, and mismatch explanation.
- https://webhooks.platphormnews.com/templates: Public-safe event payload templates.
- https://webhooks.platphormnews.com/integrations: Spec, Evals, Sandbox, AgentUI, Monitor, Trace, MCP, API, Docs, Sheets, Decks, Catalog, and CLI handoffs.
- https://webhooks.platphormnews.com/integrations/spec: Webhook contract handoff to Spec.
- https://webhooks.platphormnews.com/integrations/evals: Delivery and contract suite handoff to Evals.
- https://webhooks.platphormnews.com/integrations/sandbox: Receiver test handoff to Sandbox.
- https://webhooks.platphormnews.com/integrations/agentui: Payload form and protected action panel handoff to AgentUI.
- https://webhooks.platphormnews.com/integrations/monitor: Webhook health summary handoff to Monitor.
- https://webhooks.platphormnews.com/clients/cli: platphormctl examples for WebhookLab.
- https://webhooks.platphormnews.com/faq: WebhookLab public/protected policy and lifecycle FAQ.
- https://webhooks.platphormnews.com/api/docs: OpenAPI JSON API reference.
- https://webhooks.platphormnews.com/openapi.yaml: YAML OpenAPI document.
- https://webhooks.platphormnews.com/openapi.json: Root OpenAPI JSON document.
- https://webhooks.platphormnews.com/llms.txt: Readable agent context.
- https://webhooks.platphormnews.com/llms-full.txt: Complete agent context.
- https://webhooks.platphormnews.com/llms-index.json: Machine-readable llms index.
- https://webhooks.platphormnews.com/robots.txt: Public crawler policy.
- https://webhooks.platphormnews.com/.well-known/mcp.json: MCP server descriptor.
- https://webhooks.platphormnews.com/.well-known/agents.json: Agent platform policy descriptor.
- https://webhooks.platphormnews.com/.well-known/agent-policy.json: Agent access policy.
- https://webhooks.platphormnews.com/.well-known/ai-policy.json: AI use and crawl policy.
- https://webhooks.platphormnews.com/.well-known/trust.json: PlatPhorm trust and public/protected boundary.
- https://webhooks.platphormnews.com/.well-known/security.txt: Security contact policy.

## Capabilities
- webhook-simulation: Webhook Simulation; status=working; publicSafe=true; protected=false; human=/lab; api=/api/v1/agent; mcp=generate_test_payload
- signature-generation: Signature Generation; status=working; publicSafe=true; protected=false; human=/simulator; api=/api/v1/signatures/generate; mcp=generate_signature
- signature-verification: Signature Verification; status=working; publicSafe=true; protected=false; human=/simulator; api=/api/v1/signatures/verify; mcp=verify_signature
- endpoint-registration: Endpoint Registration; status=working; publicSafe=false; protected=true; human=/dashboard/endpoints; api=/api/v1/endpoints; mcp=register_webhook_endpoint
- event-creation-listing: Event Creation and Listing; status=working; publicSafe=true; protected=true; human=/dashboard/events; api=/api/v1/events; mcp=create_webhook_event
- delivery-tracking: Delivery Tracking; status=working; publicSafe=true; protected=false; human=/dashboard/replays; api=/api/v1/deliveries; mcp=list_deliveries
- delivery-replay: Delivery Replay; status=working; publicSafe=false; protected=true; human=/dashboard/replays; api=/api/v1/deliveries/{id}/replay; mcp=replay_webhook
- contract-creation: Contract Creation; status=working; publicSafe=false; protected=true; human=/dashboard/contracts; api=/api/v1/contracts; mcp=create_contract
- payload-validation: Payload Validation; status=working; publicSafe=true; protected=false; human=/dashboard/contracts; api=/api/v1/contracts/{id}/validate; mcp=validate_payload
- vercel-webhook-receiver: Vercel Webhook Receiver; status=working; publicSafe=false; protected=true; human=/docs; api=/api/webhooks; mcp=receive_test_webhook
- mcp-integration: MCP Integration; status=working; publicSafe=true; protected=false; human=/capabilities; api=/api/mcp; mcp=none
- agent-endpoint: Agent Endpoint; status=working; publicSafe=true; protected=true; human=/capabilities; api=/api/v1/agent; mcp=none
- docs-openapi: Docs and OpenAPI; status=working; publicSafe=true; protected=false; human=/docs; api=/api/docs; mcp=none
- discovery-files: llms, Sitemap, Robots, Feed; status=working; publicSafe=true; protected=false; human=/capabilities; api=/llms-index.json; mcp=none

## MCP tools
- get_webhooklab_info: Get WebhookLab product identity, lifecycle, and public/protected policy.; access=public-safe
- list_webhook_events: List webhook events.; access=public-safe
- get_webhook_event: Get webhook event by id.; access=public-safe
- create_webhook_event: Create and optionally send webhook event.; access=protected
- list_webhook_endpoints: List registered webhook endpoints.; access=public-safe
- get_webhook_endpoint: Get webhook endpoint by id with public-safe redaction.; access=public-safe
- register_webhook_endpoint: Register webhook endpoint.; access=protected
- update_webhook_endpoint: Update webhook endpoint.; access=protected
- delete_webhook_endpoint: Delete webhook endpoint.; access=protected
- send_webhook: Send webhook event to endpoint.; access=protected
- replay_webhook: Replay webhook delivery.; access=protected
- cancel_delivery: Cancel a pending delivery.; access=protected
- get_delivery: Get webhook delivery.; access=public-safe
- list_delivery_attempts: List delivery attempts.; access=public-safe
- generate_signature: Generate HMAC signature.; access=public-safe
- verify_signature: Verify HMAC signature.; access=public-safe
- explain_signature_failure: Explain a signature mismatch with redacted canonical-string evidence.; access=public-safe
- list_contracts: List webhook contracts.; access=public-safe
- get_contract: Get webhook contract by id.; access=public-safe
- create_contract: Create webhook contract.; access=protected
- update_contract: Update webhook contract.; access=protected
- delete_contract: Delete webhook contract.; access=protected
- validate_payload: Validate payload against contract.; access=public-safe
- generate_negative_payload: Generate negative test payload from contract schema.; access=public-safe
- run_contract_test: Run contract test.; access=protected
- receive_test_webhook: Record inbound webhook receipt.; access=protected
- sync_mcp_servers: Sync MCP server registry.; access=protected
- get_route_compliance: Get route compliance summary.; access=public-safe
- get_discovery_compliance: Get discovery file compliance summary.; access=public-safe
- generate_webhook_test_plan: Generate webhook test plan.; access=public-safe
- generate_webhook_remediation: Generate remediation guidance for failures.; access=public-safe
- get_integration_status: Get public-safe integration status matrix.; access=public-safe
- get_agent_policy: Get WebhookLab agent access policy.; access=public-safe
- list_agent_platforms: List supported agent platform categories without hardcoded unverified crawler strings.; access=public-safe
- get_agent_platform: Get agent platform policy by id.; access=public-safe
- evaluate_agent_access: Evaluate whether an action is public-safe or protected.; access=public-safe
- get_robots_policy: Get robots and sensitive-route policy.; access=public-safe
- get_ai_policy: Get AI policy summary.; access=public-safe
- get_trust_policy: Get trust policy summary.; access=public-safe
- get_discovery_manifest: Get discovery manifest with llms, OpenAPI, sitemap, RSS, robots, and well-known links.; access=public-safe
- get_public_access_summary: Get public-safe and protected access summary.; access=public-safe
- get_health: Get health summary.; access=public-safe
- get_info: Get concise WebhookLab service info.; access=public-safe
- send_contract_to_spec: Protected handoff of a contract to Spec.; access=protected
- create_evals_suite: Protected handoff to Evals for contract test-suite creation.; access=protected
- generate_sandbox_receiver_test: Protected handoff to Sandbox for receiver tests.; access=protected
- publish_monitor_status: Protected handoff of webhook health to Monitor.; access=protected
- update_agent_policy: Protected update of agent policy registry.; access=protected
- refresh_agent_platform_registry: Protected refresh of agent platform registry.; access=protected
- create_docs_report: Create docs report artifact.; access=protected
- create_sheet_report: Create sheet report artifact.; access=protected
- create_deck_summary: Create deck summary artifact.; access=protected
- create_webhook_endpoint: Backward compatible alias for register_webhook_endpoint.; access=protected
- emit_test_event: Backward compatible alias for create_webhook_event.; access=protected
- replay_event: Backward compatible alias for replay_webhook.; access=protected
- list_deliveries: Backward compatible alias for delivery listing.; access=public-safe
- generate_test_payload: Generate test payload template.; access=public-safe
- get_service_status: Get service status summary.; access=public-safe

## MCP resources
- webhooks://events: Webhook events collection
- webhooks://event/{id}: Webhook event by id
- webhooks://endpoints: Webhook endpoint registry
- webhooks://endpoint/{id}: Webhook endpoint by id
- webhooks://deliveries: Webhook deliveries
- webhooks://delivery/{id}: Webhook delivery by id
- webhooks://delivery/{id}/attempts: Webhook delivery attempts
- webhooks://contracts: Webhook contracts
- webhooks://contract/{id}: Webhook contract by id
- webhooks://templates: Public-safe webhook templates
- webhooks://signature-policy: Webhook signature policy
- webhooks://integrations: PlatPhorm integration status matrix
- webhooks://network/sites: Network sites
- webhooks://network/compliance: Route/discovery compliance
- webhooks://openapi: OpenAPI document
- webhooks://llms: LLMS discovery docs
- webhooks://trust-policy: Trust policy
- agent-policy://summary: Agent policy summary
- agent-policy://platforms: Agent platform policy categories
- agent-policy://robots: Robots policy
- agent-policy://ai-policy: AI policy
- agent-policy://trust-policy: Trust policy

## MCP prompts
- create_webhook_test: Create a webhook test case.
- explain_delivery_failure: Explain webhook delivery failure.
- generate_retry_test: Generate retry behavior test steps.
- generate_signature_test: Generate signature verification test steps.
- generate_contract_schema: Generate contract schema from payload sample.
- debug_webhook_delivery: Debug webhook delivery workflow.
- replay_webhook_safely: Replay webhook with safety checks.
- create_webhook_remediation: Create remediation workflow for failed delivery.
- create_webhook_contract: Create a webhook event contract from requirements.
- generate_sandbox_receiver_test: Generate a Sandbox receiver behavior test.
- generate_evals_contract_suite: Generate an Evals suite for webhook contract validation.
- human_machine_webhook_handoff: Generate human+agent webhook handoff summary.

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

## Tooltip terms
- eventType: Event type identifies the webhook contract and routing policy, for example webhook.test or user.created.
- endpoint: Endpoint is the protected receiver target. Server persistence and external sends require PLATPHORM_API_KEY.
- delivery: Delivery is the async job linking an event to an endpoint and its attempts.
- attempt: Attempt is one outbound request with redacted request and response evidence.
- replay: Replay resends a previous delivery only after protected authorization and confirmation.
- retryPolicy: Retry policy controls max attempts, timeout, backoff, retryable statuses, dead-letter behavior, and cancellation.
- signature: WebhookLab signatures use HMAC with timestamped canonical strings and transient secrets.
- sha256: HMAC-SHA256 signs timestamp.payload using a transient secret.
- sha512: HMAC-SHA512 signs timestamp.payload using a transient secret.
- timestamp: Timestamp headers prevent replay outside the configured tolerance window.
- idempotencyKey: Idempotency keys let receivers safely deduplicate retries and replays.
- contract: Contracts validate payload shape and event envelopes before a send becomes evidence.
- validation: Validation is deterministic and cannot be replaced by model-assisted explanation.
- payload: Payload summaries are redacted publicly and private payloads require protected access.
- publicSafe: Public-safe actions are read-only, bounded, local-only, or redacted.
- protectedAction: Protected actions mutate state, send externally, replay, cancel, publish, or expose sensitive details.
- apiKey: Protected operations use only PLATPHORM_API_KEY through Authorization bearer or X-PlatPhorm-API-Key.
- traceLink: Trace links connect events, deliveries, attempts, replays, and handoffs to trace.platphormnews.com.
- ja4: x-vercel-ja4-digest may be used for correlation only after hashing or redaction; raw values never appear publicly.
- redaction: Secrets, endpoint URLs, payloads, headers, IPs, and raw JA4 digests are redacted in public surfaces.
- apiDocs: API docs describe public-safe and protected routes with PLATPHORM_API_KEY security schemes.
- mcpTools: MCP tools advertise access policy and protected tools reject missing PLATPHORM_API_KEY.
- discovery: RSS, sitemap, robots, llms, and well-known files expose public-safe discovery only.

## Recommended platphormctl 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
- npx @platphormnews/platphormctl docs degraded generate --from-route-map <route-map.json> --json --trace
- PLATPHORM_API_KEY=... npx @platphormnews/platphormctl --include webhooks.platphormnews.com network validate --protected --best-effort --evidence --json --trace
- 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
- platphormctl harness run webhooks-contract-flow --dry-run
- platphormctl harness run spec-evals-browserops-loop --target https://webhooks.platphormnews.com --dry-run
- npx @platphormnews/platphormctl --include webhooks.platphormnews.com network validate --best-effort --evidence --json --trace