SwitchFlow delivers one unified event per payment outcome. Whether Stripe or Adyen captured the payment — and regardless of how many failover attempts it took — your endpoint receives the same normalized schema, signed with your webhook signing secret.

​
Register and verify your endpoint

  1. In the dashboard, go to Integration Kit → Webhooks and register your HTTPS endpoint URL for the environment (TEST or LIVE).
  2. Click Verify: SwitchFlow sends a signed test event and expects a 2xx response. Go-live is blocked until the live endpoint verifies.

​
Event types

TypeWhen
payment.succeededA gateway captured the payment (possibly after failover)
payment.declinedTerminal decline — no gateway approved
payment.failedNo capture for another reason; data.reason explains (e.g. gateway_blackout)
payment.refundedA refund was processed on the capturing gateway
Full payload schema with examples: Webhook events.

​
Verify signatures

Every delivery is signed (HMAC-SHA256) via the SwitchFlow-Signature header. Always verify before trusting a payload — the five-line implementation is in Verifying signatures.

​
Delivery and retries

  • Respond 2xx quickly (do heavy work asynchronously). Anything else counts as a failed delivery.
  • On 5xx or timeout, SwitchFlow retries with exponential backoff — roughly 5 min, 15 min, 45 min, 2 h, 6 h — up to 5 attempts.
  • A 4xx response is treated as terminal (your endpoint rejected the event) — no retry storm; the delivery is flagged in the dashboard.
  • After retries are exhausted the delivery is marked FAILED, you are notified by email, and the event remains visible — and manually re-deliverable — in the dashboard’s webhook log.
  • Duplicate gateway events are deduplicated upstream by idempotency key: you receive exactly one event per payment outcome. Still, treat SwitchFlow-Event-Id as an idempotency key on your side — a retry after a timeout can mean you process the same event twice.
Every delivery attempt (timestamp, response code, latency) is inspectable per event in the dashboard.