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": "2026-04-01",
"createdAt": "2026-01-01T00:00:00.000Z",
"description": "Production payment events handler",
"id": "webhook_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
"metadata": {
"environment": "prod",
"team": "payments"
},
"secret": "whsec_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
"status": "enabled",
"subscribedEvents": [
"customer.created",
"transfer.succeeded"
],
"updatedAt": "2026-01-01T00:00:00.000Z",
"url": "https://example.com/webhooks/sphere"
}{
"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
}Webhook Endpoints
Register a Webhook Endpoint for Event Delivery
Register a new webhook endpoint to receive event deliveries for the specified subscribed events.
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": "2026-04-01",
"createdAt": "2026-01-01T00:00:00.000Z",
"description": "Production payment events handler",
"id": "webhook_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
"metadata": {
"environment": "prod",
"team": "payments"
},
"secret": "whsec_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
"status": "enabled",
"subscribedEvents": [
"customer.created",
"transfer.succeeded"
],
"updatedAt": "2026-01-01T00:00:00.000Z",
"url": "https://example.com/webhooks/sphere"
}{
"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 —
Each application may hold at most six active endpoints, counting the
* 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.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
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
application/json
API version date string provided by the client.
Example:
"2026-04-01"
List of event types this endpoint should receive.
Minimum array length:
1Example:
["customer.created", "transfer.succeeded"]
The HTTPS URL to deliver webhook events to.
Maximum string length:
2048Example:
"https://example.com/webhooks/sphere"
Human-readable description of this webhook endpoint.
Maximum string length:
500Example:
"Production payment events handler"
Arbitrary key-value metadata to attach to this endpoint.
Show child attributes
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.
API version date string this endpoint was configured with, or null if not set.
Example:
"2026-04-01"
ISO 8601 timestamp when the endpoint was created.
Example:
"2026-01-01T00:00:00.000Z"
Human-readable description of this webhook endpoint, or null if not set.
Example:
"Production payment events handler"
The unique identifier of the webhook endpoint.
Example:
"webhook_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"
Arbitrary key-value metadata attached to this endpoint, or null if not set.
Example:
{ "environment": "prod", "team": "payments" }
Signing secret for this endpoint. Returned only on creation and never retrievable afterwards.
Example:
"whsec_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"
The current state of this endpoint.
Available options:
enabled, errored, disabled, deleted Example:
"enabled"
List of event types this endpoint receives.
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 Example:
["customer.created", "transfer.succeeded"]
ISO 8601 timestamp when the endpoint was last updated.
Example:
"2026-01-01T00:00:00.000Z"
The HTTPS URL events are delivered to.
Example:
"https://example.com/webhooks/sphere"
Last modified on August 27, 2026