Skip to main content
Webhooks let SpherePay notify your application the moment something happens — a customer is approved, a transfer succeeds, funds are received — so you no longer have to check GET endpoints for changes. You register an HTTPS endpoint, choose the events you care about, and SpherePay delivers a signed JSON payload to that endpoint every time one of those events occurs.

​
How it works

  1. Register a webhook endpoint. Call POST /v2/webhook-endpoints with your URL and the list of events you want to subscribe to. The response includes a signing secret — store it securely; it is shown exactly once.
  2. An event occurs. A resource in your application changes state — for example, a transfer moves from processing to succeeded.
  3. SpherePay delivers the event. SpherePay sends an HTTP POST to every enabled endpoint subscribed to that event type. The request carries a signed payload describing the state transition.
  4. You verify and process. Your handler verifies the signature, applies the state change, and responds with a 2xx status code within 15 seconds.

​
Core concepts

SpherePay’s webhook system tracks three distinct records for every notification, and all three are visible through the Events API: Each record carries its own identifier and timestamps — see Events, deliveries, and attempts for how they map to the payload body and headers, and which ones to trust when ordering state.

​
Delivery semantics

Understanding these guarantees is essential to building a reliable consumer:
  • At-least-once delivery. You may occasionally receive the same event more than once. Deduplicate using the event id in the body — it is stable across every delivery and replay of the same event.
  • No automatic retries. SpherePay makes exactly one delivery attempt per event per endpoint. If your endpoint returns a non-2xx response, or does not respond within 15 seconds, the delivery is marked failed and SpherePay does not retry it automatically. You can replay a failed delivery at any time via the Events API.
  • Delivery order is not guaranteed. Replays, parallel workers, and network jitter can all cause out-of-order arrival. Every payload carries a sequence field so you can detect and discard stale updates.
  • Minimal payloads. Event payloads describe the state transition — the previous status and the new status — not the full resource. When you need the complete object, call the resource’s GET endpoint. See Event payloads.
Because there are no automatic retries in the current release, make your webhook handler fast and resilient: acknowledge with a 2xx immediately after verifying the signature, and do heavy processing asynchronously. A slow handler that exceeds the 15-second window will cause deliveries to be marked failed.

​
Responding to a delivery

Return any 2xx status code to acknowledge receipt. Anything else — including redirects, which SpherePay does not follow — marks the delivery as failed.

​
Explore

Manage webhook endpoints

Register, list, and delete webhook endpoints, and understand endpoint limits and states.

Event payloads

The envelope structure, the sequence field, and how applicationId scopes each event.

Event catalog

Every event subject you can subscribe to, with triggers and example payloads.

Verify signatures

Authenticate deliveries with HMAC-SHA256 — with snippets in Python, JavaScript, Go, Java, and C#.

Events and replays

Browse your event history, inspect delivery attempts, and replay failed deliveries.
Last modified on August 11, 2026