Managing Webhook Endpoints

A webhook endpoint is a URL you register with SpherePay together with the list of events it should receive. This page covers the full endpoint lifecycle: creating an endpoint, listing and retrieving endpoints, and deleting them.

Register an endpoint

Create an endpoint with POST /v2/webhook-endpoints:

curl -X POST https://api.spherepay.co/v2/webhook-endpoints \
  -H "Authorization: Bearer {{api_key}}" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/sphere-webhook",
    "subscribedEvents": ["customer.approved", "customer.rejected", "transfer.*"],
    "apiVersion": "2026-08-01",
    "description": "Production onboarding and transfer events",
    "metadata": { "team": "payments", "environment": "prod" }
  }'

Field	Required	Description
`url`	Yes	The URL SpherePay delivers events to. Must be HTTPS in live mode. Maximum 2,048 characters.
`subscribedEvents`	Yes	One or more event names from the event catalog, or a wildcard: `` (all events) or a resource wildcard such as `customer.` or `transfer.*`.
`apiVersion`	Yes	A `YYYY-MM-DD` API version date. Must be a valid calendar date and must not be in the future.
`description`	No	Free-text label, up to 500 characters.
`metadata`	No	Key-value pairs for your own bookkeeping — for example, to track registered endpoints within your system.

The response returns the endpoint and its signing secret:

{
  "id": "whk_01HXP9TN3J2ABC",
  "url": "https://api.example.com/sphere-webhook",
  "subscribedEvents": ["customer.approved", "customer.rejected", "transfer.*"],
  "status": "enabled",
  "apiVersion": "2026-08-01",
  "secret": "whsec_9f8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c",
  "description": "Production onboarding and transfer events",
  "metadata": { "team": "payments", "environment": "prod" },
  "createdAt": "2026-08-07T10:00:00Z",
  "updatedAt": "2026-08-07T10:00:00Z"
}

The secret (prefixed whsec_) is returned exactly once, in the creation response. It is never returned by GET requests and cannot be retrieved later. Store it securely — you need it to verify the signature on every delivery. Each endpoint has its own distinct secret; secrets are never shared across endpoints.

Newly created endpoints are enabled immediately and begin receiving events that match their subscription.

Updating an endpoint: delete and recreate

There is currently no update operation for webhook endpoints. To change an endpoint’s URL, subscribed events, or any other property, delete the endpoint and create a new one. The same applies to rotating a signing secret — deleting an endpoint invalidates its secret, and the replacement endpoint receives a fresh one.

In-place endpoint updates are coming soon — a future release will let you modify an existing endpoint’s URL and subscriptions without recreating it. Until then, use the delete-and-recreate flow below.

For a zero-gap migration:

Create the new endpoint with the updated configuration. Both endpoints now receive events.
Confirm the new endpoint is receiving and verifying deliveries.
Delete the old endpoint.

During step 1 both endpoints receive matching events, so your handlers should be idempotent — deduplicate on the event id in the payload body.

List and retrieve endpoints

curl "https://api.spherepay.co/v2/webhook-endpoints?page=1&limit=10" \
  -H "Authorization: Bearer {{api_key}}"

List query parameters:

Parameter	Description
`page`	Page number, starting at `1` (default `1`).
`limit`	Results per page (default `10`, maximum `100`).
`status`	Filter by endpoint state: `enabled`, `disabled`, or `errored`.
`subscribedEvents`	Comma-separated event names; returns endpoints subscribed to at least one of them. Wildcard values (``, `customer.`, `transfer.*`) are accepted.

The subscribedEvents filter matches literally against each endpoint’s subscription list — it does not expand wildcards. Filtering by transfer.* returns endpoints that subscribed with the transfer.* wildcard itself, not endpoints subscribed to individual events like transfer.succeeded (and vice versa). To find every endpoint that would receive a given event, filter by both forms: subscribedEvents=transfer.succeeded,transfer.*,*.

List responses use SpherePay’s standard pagination envelope: { "data": [...], "page", "limit", "total", "totalPages", "hasNext", "hasPrevious" }. Retrieve a single endpoint with GET /v2/webhook-endpoints/{id}. The secret field is never included.

Delete an endpoint

curl -X DELETE https://api.spherepay.co/v2/webhook-endpoints/{{webhook_endpoint_id}} \
  -H "Authorization: Bearer {{api_key}}"

Deletion returns 204 No Content, transitions the endpoint to the deleted state, invalidates its signing secret, and stops all future deliveries. This is terminal and cannot be undone — to resume delivery, create a new endpoint.

Endpoint limits

Each application may have at most 6 active webhook endpoints — endpoints in the enabled, disabled, or errored state. Deleted endpoints do not count toward the limit. Exceeding it returns 409 Conflict.

Endpoint states

State	Meaning
`enabled`	Receiving deliveries. The initial state after registration.
`disabled`	Not receiving deliveries.
`errored`	Reserved for delivery-failure handling in a future release.
`deleted`	Terminal. The endpoint no longer exists for delivery purposes and its secret is invalid.

Only enabled endpoints receive deliveries.

Failed deliveries do not disable your endpoint. In the current release, SpherePay never changes an endpoint’s state based on delivery outcomes: if your endpoint returns a non-2xx response or times out, the individual delivery is marked failed and no automatic retry occurs, but the endpoint stays enabled and continues receiving subsequent events. Recover missed events with a manual replay.

Errors

Condition	HTTP status	Description
Unknown event name in `subscribedEvents`	`400`	The event type is not in the published catalog.
Invalid `apiVersion`	`400`	Not a valid `YYYY-MM-DD` calendar date, or a date in the future.
Endpoint not found	`404`	The webhook endpoint ID does not exist.
Endpoint limit exceeded	`409`	The application already has 6 active endpoints.

Onboarding

Transfers

Automation

Webhooks

Reference data

Operational

Managing Webhook Endpoints

Register an endpoint

Updating an endpoint: delete and recreate

List and retrieve endpoints

Delete an endpoint

Endpoint limits

Endpoint states

Errors

​Register an endpoint

​Updating an endpoint: delete and recreate

​List and retrieve endpoints

​Delete an endpoint

​Endpoint limits

​Endpoint states

​Errors

Register an endpoint

Updating an endpoint: delete and recreate

List and retrieve endpoints

Delete an endpoint

Endpoint limits

Endpoint states

Errors