Ramp Webhook Verification and Processing

Overview

Verify authenticity before parsing, acknowledge only after durable receipt, and treat each event as a notification to reconcile current resource state. Design for retries, duplicates, and out-of-order delivery.

Prerequisites

• Identify the Ramp application, environment, business entities, affected data and workflows, accountable owner, and rollback boundary.
• Read references/official-docs.md and re-check endpoint schemas, scopes, limits, and support status before a live operation.
• Use synthetic fixtures or Ramp sandbox until production access and business effects are explicitly approved.
• Prepare approved secret storage and a sanitized evidence location.

Current Contract

• New subscriptions begin pending_verification; Ramp sends a challenge that must be returned and submitted to activate the subscription.
• Business deliveries include X-Ramp-Webhook-ID and X-Ramp-Signature; the latter is HMAC-SHA256 of the exact raw request body using the subscription secret.
• Receivers must respond within 10 seconds. Ramp retries 429, 5xx, timeouts, and connection errors up to 10 total attempts with exponential backoff and jitter.
• The same event ID is reused across retries, and events may arrive out of order.