Webhooks

Webhooks allow SpherePay to notify your server in real time when an event occurs — such as a transfer completing, a customer's KYC status changing, or a payment failing. Rather than polling the API for status changes, your server receives an HTTP POST request with the event payload as soon as the change happens.

Setting up a webhook endpoint

Before SpherePay can send events to your server, you need to register a webhook endpoint in the Dashboard:

1. Log in to spherepay.co/dashboard.
2. Navigate to Settings → Webhooks.
3. Click Add Endpoint.
4. Enter the URL of the endpoint on your server that will receive events (e.g. https://yourapp.com/webhooks/spherepay).
5. Select the event types you want to receive.
6. Save the endpoint.

SpherePay will begin sending POST requests to your endpoint immediately.

Receiving an event

Each webhook delivery is an HTTP POST request to your endpoint with a JSON body. The request includes a Content-Type: application/json header.

A sample event payload:

{
  "id": "evt_abc123",
  "type": "transfer.succeeded",
  "createdAt": "2026-02-25T12:00:00.000Z",
  "data": {
    "id": "transfer_xyz789",
    "status": "succeeded",
    "amount": "100.00",
    "currency": "usd",
    "customerId": "customer_abc123"
  }
}

Your endpoint must return a 2xx HTTP status code within 30 seconds to acknowledge receipt. If SpherePay does not receive a 2xx response, the event will be retried with exponential backoff.

Handling events

Your webhook handler should:

1. Return a 200 OK response immediately upon receipt, before performing any processing.
2. Process the event asynchronously to avoid timeout failures.
3. Use the event id to deduplicate deliveries — SpherePay guarantees at-least-once delivery, meaning an event may occasionally be delivered more than once.

// Example: Express.js webhook handler
app.post('/webhooks/spherepay', express.json(), (req, res) => {
  // Acknowledge receipt immediately
  res.sendStatus(200);

  const event = req.body;

  // Process asynchronously
  handleEvent(event);
});

async function handleEvent(event) {
  switch (event.type) {
    case 'transfer.succeeded':
      await markTransferComplete(event.data.id);
      break;
    case 'kyc.approved':
      await updateCustomerStatus(event.data.customerId);
      break;
    default:
      console.log(`Unhandled event type: ${event.type}`);
  }
}

Signature verification

Retry behaviour

If your endpoint fails to return a 2xx response, SpherePay will retry the delivery with exponential backoff over a 72-hour window. After all retries are exhausted, the event is marked as failed and is visible in the Dashboard under Settings → Webhooks → Failed Events, where you can trigger a manual replay.

Viewing events in the Dashboard

All webhook deliveries — successful and failed — are visible in the Dashboard under Settings → Webhooks. Each delivery shows the event payload, the HTTP response your endpoint returned, and the delivery timestamp. This is useful for debugging integration issues during development.