Webhooks

Purpose

Endpoints where a third party (originally Paddle; as of 2026-08-23, Swich and Shopify — see that update below) calls into SellVia, rather than the frontend calling out.

Original (superseded 2026-08-23 — see Update below): Inbound Only (Paddle → SellVia)

• POST /webhooks/paddle — the single endpoint handling all Paddle event types (transaction.completed, charge.refunded, payout.paid, payout.failed, seller.updated), per 02. Event-Driven Architecture
• Secured via Paddle signature verification only (04. Security → Webhook Security) — not user-session-authenticated, since Paddle isn't a logged-in user

Future: Outbound (SellVia → Merchant's Store), v2

Once external-site tracking is built (deferred per Money Flow), SellVia would need to receive webhooks FROM a merchant's Shopify store (order created/paid), which is architecturally the reverse direction from today's single Paddle-inbound webhook. Not designed yet — flagged here as a known future addition, not built now.

Open Questions

• None blocking for MVP — the v2 outbound-direction webhook system is intentionally undesigned until the external-tracking decision is revisited.

Update (2026-08-07): This Is Now Active, Not Deferred

The "Future: Outbound (SellVia → Merchant's Store), v2" section above is now the current MVP mechanism, not deferred — 01. Money Flow's checkout reversal made external-site sale reporting the actual model. Resolved as a universal onboarding tracking snippet (05. Payment Flow), not a bespoke per-platform integration like a Shopify app — simpler than what this doc originally anticipated needing to build.

Update (2026-08-23): MAJOR REVISION — Shopify Webhook Replaces the Snippet, Paddle Replaced by Swich

Founder decisions, full reasoning in 02. Architecture Decision Log. Both prior updates on this page are partially superseded:

Inbound, revised — two webhook sources now, not one:

• POST /webhooks/swich — replaces POST /webhooks/paddle. Handles billing-payment-confirmed, payout-confirmed, and payout-failed events (exact event names unconfirmed pending real Swich integration — see 03. Table Specifications, 07. Endpoint Specifications, both updated 2026-08-23). Secured via Swich's own signature-verification scheme (shape unconfirmed), same non-session-authenticated pattern as the Paddle handler it replaces.
• POST /webhooks/shopify-sales — the merchant-integration direction. The 2026-08-07 "This Is Now Active" update above is itself superseded: the universal onboarding snippet it describes is retired for MVP. "For now we are just going with Shopify only" — this endpoint receives Shopify's native orders/paid webhook per merchant store, not a snippet report. Secured via Shopify's own webhook HMAC verification, per-store.

Not a rename, an architectural simplification: the original "Future: Outbound" framing anticipated needing to build and maintain a bespoke integration per e-commerce platform. Scoping MVP to Shopify-only removes that multi-platform burden entirely — one webhook shape to handle, not an abstraction layer over many.

Currency: PKR only in every payload.