> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spherepay.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Webhooks Overview
> Receive real-time notifications when customers, transfers, and other SpherePay resources change state — instead of polling for updates.
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`](/concepts/webhooks/managing-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](/concepts/webhooks/verifying-signatures), 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](/concepts/webhooks/events-and-replays):
| Concept | Meaning |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Event** | A fact about something that happened in SpherePay — one per occurrence, immutable once created. Identified by an `event_` ID in the payload body. |
| **Event delivery** | One event being routed to one of your webhook endpoints. If two endpoints subscribe to the same event type, one event produces two deliveries. |
| **Delivery attempt** | A single HTTP request from SpherePay to your endpoint. Each attempt records the response code, latency, and whether it succeeded. |
Each record carries its own identifier and timestamps — see [Events, deliveries, and attempts](/concepts/webhooks/event-payloads#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](/concepts/webhooks/events-and-replays#replaying-a-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](/concepts/webhooks/event-payloads#the-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](/concepts/webhooks/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
Register, list, and delete webhook endpoints, and understand endpoint limits and states.
The envelope structure, the `sequence` field, and how `applicationId` scopes each event.
Every event subject you can subscribe to, with triggers and example payloads.
Authenticate deliveries with HMAC-SHA256 — with snippets in Python, JavaScript, Go, Java, and C#.
Browse your event history, inspect delivery attempts, and replay failed deliveries.