Webhook

Webhooks let SpherePay notify your system when something changes (for example, a transfer status update) by sending an HTTP POST request to an endpoint you control.

Instead of continuously polling the API, you subscribe to events and process notifications as they arrive.

What you need to implement

• A public webhook endpoint: an HTTPS URL that can receive POST requests.
• Fast acknowledgement: return a 2xx response quickly so SpherePay knows you received the event.
• Durable processing: store the payload and process it asynchronously (queue/worker) so transient errors don’t lose events.
• Idempotency: handle retries safely (the same event may be delivered more than once).

Why webhooks matter for SpherePay integrations

Most SpherePay workflows are asynchronous. For example, ACH and wire transfers can take time to settle, and the final status is not immediately known when you create a transfer.

Webhooks give you reliable status updates so your product can react at the right moment.

Handling asynchronous flows

Use webhooks to:

• Update UI and internal records when transfers move through their lifecycle
• Trigger business logic (for example, mark an invoice as paid, release an order, or initiate fulfilment)
• Avoid building fragile polling loops

State synchronization

Webhook payloads include the latest data for the event, so you can use them to keep your database in sync even when updates are initiated outside your system.

Next steps

• Set up webhooks: /guide/reference/webhooks/set-up-webhook
• Manage your webhook endpoints: /guide/reference/webhooks/manage-webhook
• Event types and payloads: /guide/reference/webhooks/events