Register a Webhook Endpoint for Event Delivery

Create a Webhook Endpoint V2

curl --request POST \
  --url https://api.spherepay.co/v2/webhook-endpoints \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "apiVersion": "2026-04-01",
  "subscribedEvents": [
    "customer.created",
    "transfer.succeeded"
  ],
  "url": "https://example.com/webhooks/sphere",
  "description": "Production payment events handler",
  "metadata": {
    "environment": "prod",
    "team": "payments"
  }
}
'

import requests

url = "https://api.spherepay.co/v2/webhook-endpoints"

payload = {
    "apiVersion": "2026-04-01",
    "subscribedEvents": ["customer.created", "transfer.succeeded"],
    "url": "https://example.com/webhooks/sphere",
    "description": "Production payment events handler",
    "metadata": {
        "environment": "prod",
        "team": "payments"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    apiVersion: '2026-04-01',
    subscribedEvents: ['customer.created', 'transfer.succeeded'],
    url: 'https://example.com/webhooks/sphere',
    description: 'Production payment events handler',
    metadata: {environment: 'prod', team: 'payments'}
  })
};

fetch('https://api.spherepay.co/v2/webhook-endpoints', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.spherepay.co/v2/webhook-endpoints",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'apiVersion' => '2026-04-01',
    'subscribedEvents' => [
        'customer.created',
        'transfer.succeeded'
    ],
    'url' => 'https://example.com/webhooks/sphere',
    'description' => 'Production payment events handler',
    'metadata' => [
        'environment' => 'prod',
        'team' => 'payments'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.spherepay.co/v2/webhook-endpoints"

	payload := strings.NewReader("{\n  \"apiVersion\": \"2026-04-01\",\n  \"subscribedEvents\": [\n    \"customer.created\",\n    \"transfer.succeeded\"\n  ],\n  \"url\": \"https://example.com/webhooks/sphere\",\n  \"description\": \"Production payment events handler\",\n  \"metadata\": {\n    \"environment\": \"prod\",\n    \"team\": \"payments\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.spherepay.co/v2/webhook-endpoints")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"apiVersion\": \"2026-04-01\",\n  \"subscribedEvents\": [\n    \"customer.created\",\n    \"transfer.succeeded\"\n  ],\n  \"url\": \"https://example.com/webhooks/sphere\",\n  \"description\": \"Production payment events handler\",\n  \"metadata\": {\n    \"environment\": \"prod\",\n    \"team\": \"payments\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.spherepay.co/v2/webhook-endpoints")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"apiVersion\": \"2026-04-01\",\n  \"subscribedEvents\": [\n    \"customer.created\",\n    \"transfer.succeeded\"\n  ],\n  \"url\": \"https://example.com/webhooks/sphere\",\n  \"description\": \"Production payment events handler\",\n  \"metadata\": {\n    \"environment\": \"prod\",\n    \"team\": \"payments\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "apiVersion": "<string>",
  "createdAt": "<string>",
  "description": "<string>",
  "id": "<string>",
  "metadata": null,
  "secret": "whsec_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "status": "enabled",
  "subscribedEvents": [
    "*"
  ],
  "updatedAt": "<string>",
  "url": "<string>"
}

{
  "code": "address/invalid",
  "correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
  "detail": "Invalid request parameters",
  "status": 400
}

{
  "code": "resource/not-found",
  "correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
  "detail": "Resource not found",
  "status": 404
}

{
  "code": "validation/failed",
  "correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
  "detail": "Validation failed",
  "errors": [
    {
      "detail": "Invalid email format",
      "pointer": "/email"
    },
    {
      "detail": "Name is required",
      "pointer": "/name"
    }
  ],
  "status": 422
}

Create a Webhook Endpoint V2

curl --request POST \
  --url https://api.spherepay.co/v2/webhook-endpoints \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "apiVersion": "2026-04-01",
  "subscribedEvents": [
    "customer.created",
    "transfer.succeeded"
  ],
  "url": "https://example.com/webhooks/sphere",
  "description": "Production payment events handler",
  "metadata": {
    "environment": "prod",
    "team": "payments"
  }
}
'

import requests

url = "https://api.spherepay.co/v2/webhook-endpoints"

payload = {
    "apiVersion": "2026-04-01",
    "subscribedEvents": ["customer.created", "transfer.succeeded"],
    "url": "https://example.com/webhooks/sphere",
    "description": "Production payment events handler",
    "metadata": {
        "environment": "prod",
        "team": "payments"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    apiVersion: '2026-04-01',
    subscribedEvents: ['customer.created', 'transfer.succeeded'],
    url: 'https://example.com/webhooks/sphere',
    description: 'Production payment events handler',
    metadata: {environment: 'prod', team: 'payments'}
  })
};

fetch('https://api.spherepay.co/v2/webhook-endpoints', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.spherepay.co/v2/webhook-endpoints",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'apiVersion' => '2026-04-01',
    'subscribedEvents' => [
        'customer.created',
        'transfer.succeeded'
    ],
    'url' => 'https://example.com/webhooks/sphere',
    'description' => 'Production payment events handler',
    'metadata' => [
        'environment' => 'prod',
        'team' => 'payments'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.spherepay.co/v2/webhook-endpoints"

	payload := strings.NewReader("{\n  \"apiVersion\": \"2026-04-01\",\n  \"subscribedEvents\": [\n    \"customer.created\",\n    \"transfer.succeeded\"\n  ],\n  \"url\": \"https://example.com/webhooks/sphere\",\n  \"description\": \"Production payment events handler\",\n  \"metadata\": {\n    \"environment\": \"prod\",\n    \"team\": \"payments\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.spherepay.co/v2/webhook-endpoints")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"apiVersion\": \"2026-04-01\",\n  \"subscribedEvents\": [\n    \"customer.created\",\n    \"transfer.succeeded\"\n  ],\n  \"url\": \"https://example.com/webhooks/sphere\",\n  \"description\": \"Production payment events handler\",\n  \"metadata\": {\n    \"environment\": \"prod\",\n    \"team\": \"payments\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.spherepay.co/v2/webhook-endpoints")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"apiVersion\": \"2026-04-01\",\n  \"subscribedEvents\": [\n    \"customer.created\",\n    \"transfer.succeeded\"\n  ],\n  \"url\": \"https://example.com/webhooks/sphere\",\n  \"description\": \"Production payment events handler\",\n  \"metadata\": {\n    \"environment\": \"prod\",\n    \"team\": \"payments\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "apiVersion": "<string>",
  "createdAt": "<string>",
  "description": "<string>",
  "id": "<string>",
  "metadata": null,
  "secret": "whsec_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "status": "enabled",
  "subscribedEvents": [
    "*"
  ],
  "updatedAt": "<string>",
  "url": "<string>"
}

{
  "code": "address/invalid",
  "correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
  "detail": "Invalid request parameters",
  "status": 400
}

{
  "code": "resource/not-found",
  "correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
  "detail": "Resource not found",
  "status": 404
}

{
  "code": "validation/failed",
  "correlationId": "28c61e885c6e5eaa78c1a2183a9b883c",
  "detail": "Validation failed",
  "errors": [
    {
      "detail": "Invalid email format",
      "pointer": "/email"
    },
    {
      "detail": "Name is required",
      "pointer": "/name"
    }
  ],
  "status": 422
}

Use this endpoint to register a URL that SpherePay delivers events to, together with the list of events it should receive. Subscribe with exact event names from the event catalog, or with a wildcard — * for everything, or a resource wildcard such as customer.*. A new endpoint is enabled immediately and starts receiving matching events.

The signing secret (prefixed whsec_) is returned exactly once, in this response. No GET returns it and it cannot be retrieved later. Store it securely — you need it to verify the signature on every delivery.

Each application may hold at most six active endpoints, counting the enabled, disabled, and errored states. Exceeding that returns 409. There is no update operation, so changing a URL or a subscription means creating a replacement and deleting the old endpoint — see managing endpoints for the zero-gap sequence.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

apiVersion

string

required

API version date string provided by the client.

Example:

"2026-04-01"

subscribedEvents

string[]

required

List of event types this endpoint should receive.

Minimum array length: 1

Example:

["customer.created", "transfer.succeeded"]

url

string<uri>

required

The HTTPS URL to deliver webhook events to.

Maximum string length: 2048

Example:

"https://example.com/webhooks/sphere"

description

string

Human-readable description of this webhook endpoint.

Maximum string length: 500

Example:

"Production payment events handler"

metadata

object

Arbitrary key-value metadata to attach to this endpoint.

Show child attributes

Example:

{ "environment": "prod", "team": "payments" }

Response

The created webhook endpoint, including the signing secret. The secret is returned only here and cannot be retrieved again.

apiVersion

string | null

required

createdAt

string

required

description

string | null

required

string

required

metadata

unknown

required

secret

string

required

Signing secret for this endpoint. Returned only on creation and never retrievable afterwards.

Example:

"whsec_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"

status

enum<string>

required

Available options:

enabled,

errored,

disabled,

deleted

subscribedEvents

enum<string>[]

required

Available options:

*,

customer.*,

transfer.*,

document.*,

service.*,

customer.created,

customer.pending,

customer.approved,

customer.rejected,

transfer.created,

transfer.pendingFunding,

transfer.pendingReview,

transfer.fundsReceived,

transfer.processing,

transfer.succeeded,

transfer.returned,

transfer.pendingRefundInformation,

transfer.failed,

transfer.canceled,

transfer.refunded,

transfer.unexpectedError,

transfer.failedPrecondition,

transfer.expired,

transfer.unfunded,

document.pending,

document.processing,

document.verified,

document.rejected,

service.pending,

service.processing,

service.succeeded,

service.failed,

service.cancelled

updatedAt

string

required

url

string

required

Last modified on August 27, 2026

Onboarding

Accounts

Money movement

Webhooks

Register a Webhook Endpoint for Event Delivery

Authorizations

Body

Response