integrate-webhook

Integrate webhook

Webhooks drive a transfer's lifecycle after the quote: awaiting_payment → settling → completed | failed | expired. Implement one WebhookProcessor in apps/sdp-api/src/routes/webhooks/ramps/<id>.ts using the interface in processor.ts:

• verify(context) — verify the signature, return the parsed payload.
• parse(payload) — pure wire-format → RampSettlementEvent mapping.
• process(c, environment, event) — DB orchestration; calls applyRampSettlementEvent.

Canonical examples: the registered processors in apps/sdp-api/src/routes/webhooks/ramps/ — read the closest one before writing yours.

Mount + flow

Webhooks are not under /v1. They land at POST /webhooks/payments/ramps/{sandbox|production}/:provider. parseRampWebhookProvider accepts an id only after registration in apps/sdp-api/src/routes/webhooks/handlers.ts. The handler reads the raw body → verifies → parses → returns 2xx → runs process through c.executionCtx.waitUntil.

verify

verify(context: RampWebhookValidationContext): Promise<Payload>. context = { env, environment, headers, rawBody, requestUrl? }. Read the mode-keyed verification secret/key from env, verify the signature over the raw body, then JSON.parse and return the payload. Throw UNAUTHORIZED on a missing/invalid signature; throw badRequest on non-JSON. Use apps/sdp-api/src/lib/webhook-signature.ts and supply the upstream timestamp as timestampSeconds; the helper enforces replay tolerance as well as signature verification.

The shared verifier currently supports HMAC-SHA256 and ECDSA P-256/SHA-256, and it requires a provider-signed timestamp. If the upstream uses another algorithm or does not sign a timestamp, stop and extend/review the shared verification contract; do not fabricate a local timestamp or bypass replay protection.

This is one of the few places unknown is allowed — it's a genuine trust boundary, narrowed immediately by parse.

Signature variety across the six registered webhook providers: