chore: streamline webhook reconciliation guide

[MantisClone]

Problem

Webhook reconciliation repeats an obsolete event catalog and handler examples, so it can diverge from the current webhook contract.

REQ-420

Proposed Solution

• Point integrators to the Webhooks reference for events, recipients, payloads, and legacy integrations.
• Update the Express example for current Secure Payment and orchestrator events.
• Keep verified test deliveries from changing application state and retain raw-body signature verification and delivery-id idempotency.

Considerations

• This stacks on #132 and keeps the existing page and navigation structure.
• It describes public API behavior from the current webhook-delivery work. This documentation should merge only after that behavior is included in the public API release.
• The platform and orchestrator registration instructions remain in the Webhooks reference; this page is a handler tutorial.

UAT

1. Open the PR preview. The event-selection section should link to the canonical reference for current events, recipients, payloads, and legacy integrations.
2. Inspect the Express handler. It should verify the raw body before parsing, return 200 for a verified x-request-network-test: true delivery before handleEvent, and pass x-request-network-delivery to each business operation.
3. Confirm that the example covers client_id.linked, payment.confirmed, payment.failed, kyt.screening.completed, secure_payment.user_event, and secure_payment.access_rejected, and that the setup note distinguishes the platform and orchestrator signing secrets.

[MantisClone]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• chore: streamline quickstart webhook guidance #134
• chore: streamline webhook reconciliation guide #133 👈 (View in Graphite)
• chore: document current webhook delivery #132
• chore: consolidate webhook guidance #130
• fix: remove unused webhook event variants #129
• chore: add webhook payload examples #131
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[greptile-apps]

Greptile Summary

The PR consolidates webhook event guidance into the canonical reference and updates the reconciliation example for platform and orchestrator deliveries.

• Adds separate signing-secret configuration and raw-body verification across both endpoint roles.
• Prevents verified test deliveries from reaching state-changing handlers.
• Refreshes event routing and preserves delivery-ID idempotency guidance.

Confidence Score: 4/5

The PR is not yet safe to merge because the shared callback example discards the endpoint owner that authenticated each delivery.

The handler accepts either role's signature but collapses the result to a boolean, leaving downstream processing unable to distinguish platform and orchestrator registration context for shared event types.

Files Needing Attention: use-cases/webhook-reconciliation.mdx

Important Files Changed

Filename	Overview
use-cases/webhook-reconciliation.mdx	Updates the reconciliation tutorial for dual-role webhook verification and current events, but loses the matched endpoint-owner context before business dispatch.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  P[Platform delivery] --> V[Verify against configured secrets]
  O[Orchestrator delivery] --> V
  V --> M[Retain matching endpoint owner]
  M --> T{Test delivery?}
  T -->|Yes| A[Acknowledge without state change]
  T -->|No| H[Handle event with delivery ID and owner context]

Loading

_{Reviews (3): Last reviewed commit: "chore: streamline webhook reconciliation..." | Re-trigger Greptile}

[greptile-apps]

Endpoint owner context is lost

When one callback URL receives events for both a platform and an orchestrator, matchesKnownSignature reduces the matching secret to a boolean and passes no endpoint-owner identity to handleEvent, causing shared event types to be routed without knowing which registration authenticated the delivery.

Knowledge Base Used:

• Webhook events and delivery
• Webhook reconciliation