Webhooks
Webhooks allow you to propagate event data to your servers.
You can use webhooks to listen for events on your Sphere account and get automatically notified when key events, such as a successful purchase, successful transfer, charge dispute, or subscription payment collection happen, and take appropriate actions like updating your database or sending out an e-mail.
You may create up to 10 webhooks at a time, and each webhook can listen to as many events as desired.
The average response time of Sphere webhook requests is under 5000ms.
Verifying webhook requests
To verify that a webhook request is coming from Sphere, you can use the signature
header. The value of the header is a HMAC-SHA256 signature of the request body, using the webhook secret as the key.
Verifying HMAC SHA256 Signature
import crypto from "crypto";
const signature = crypto
.createHmac("sha256", Buffer.from(webhook.secret))
.update(JSON.stringify(req.body), "utf8")
.digest("hex");
if (signature !== req.headers["signature"]) {
console.log("Invalid signature");
}
The Webhook object
Properties
- Name
id
- Type
- string
- Description
A unique identifier for the object.
- Name
name
- Type
- string
- Description
A name for the webhook. Max length (500).
- Name
description
- Type
- string
- Description
A description for the webhook. Max length (500).
- Name
active
- Type
- boolean
- Description
Whether the webhook is actively propagating events or not.
- Name
status
- Type
- enum
- Description
The health of the webhook. One of
healthy
,degraded
,failing
, ordead
.
- Name
events
- Type
- string array
- Description
The events the webhook is listening for. All events are listed here. You are able to include
'*'
to listen to all events.
- Name
deliveryRate
- Type
- number
- Description
The delivery rate of the webhook.
0
means a 0% delivery rate, and1
means a 100% delivery rate.
- Name
url
- Type
- string
- Description
The HTTP URL endpoint that Sphere will send notifications to upon events triggering.
- Name
secret
- Type
- string
- Description
The SHA256 HMAC secret used to sign webhook events. Used to verify that messages sent to your url are coming from Sphere, and not spam from a malicious actor if your url gets exposed.
- Name
updated
- Type
- string
- Description
Datetime of when the webhook was last updated.
- Name
created
- Type
- string
- Description
Datetime of when the webhook was created.
Webhook Object
{
"id": "webhook_dab187e460e54595a76f66d38b0ee624",
"name": "Example Webhook",
"description": "An example webhook",
"active": true,
"deliveryRate": "1",
"status": "healthy",
"events": [
"bankAccount.create",
"wallet.create"
],
"url": "https://example.com/webhook",
"secret": "secret_cb8dedcf79a84b04b163ec74c7146481",
"updated": "2024-08-15T17:55:57.879Z",
"created": "2024-08-15T17:55:57.879Z"
}
Create a webhook
Creates a new webhook
object that will listen to and send events to a given URL.
Parameters
- Name
events
- Type
- string array
- Required
- Required
- Description
The names of the events that the webhook will listen for. All events are listed here. You are able to include
'*'
to listen to all events.
- Name
url
- Type
- string
- Required
- Required
- Description
The HTTP URL endpoint that Sphere will send notifications to upon events triggering.
- Name
name
- Type
- string
- Description
A name for the webhook. Max length (500).
- Name
description
- Type
- string
- Description
An description for the webhook. Max length (500).
Request
curl https://api.spherepay.co/v1/webhook \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d "{
\"name\": \"Example Webhook\",
\"description\": \"An example webhook\",
\"url\": \"https://example.com/webhook\",
\"events\": [\"bankAccount.create, wallet.create\"]
}"
Response
{
"ok": true,
"object": "object",
"statusCode": 200,
"error": null,
"message": "success",
"data": {
"webhook": {
"id": "webhook_dab187e460e54595a76f66d38b0ee624",
"name": "Example Webhook",
"description": "An example webhook",
"active": true,
"deliveryRate": "1",
"status": "healthy",
"events": [
"bankAccount.create",
"wallet.create"
],
"url": "https://example.com/webhook",
"secret": "secret_cb8dedcf79a84b04b163ec74c7146481",
"updated": "2024-08-15T17:55:57.879Z",
"created": "2024-08-15T17:55:57.879Z"
}
},
"ts": "2024-08-15T17:55:57.888Z",
"request": "request_778ada59642d4578af188873d0ce191b"
}
Retrieve a webhook
Retrieves a webhook
object by id
.
Request
curl https://api.spherepay.co/v1/webhook/webhook_dab187e460e54595a76f66d38b0ee624 \
-H "Authorization: Bearer {token}"
Response
{
"ok": true,
"object": "object",
"statusCode": 200,
"error": null,
"message": "success",
"data": {
"webhook": {
"id": "webhook_dab187e460e54595a76f66d38b0ee624",
"name": "Example Webhook",
"description": "An example webhook",
"active": true,
"deliveryRate": "0",
"status": "failing",
"events": [
"bankAccount.create",
"wallet.create"
],
"url": "https://example.com/webhook",
"secret": "secret_cb8dedcf79a84b04b163ec74c7146481",
"updated": "2024-08-16T00:00:00.397Z",
"created": "2024-08-15T17:55:57.879Z"
}
},
"ts": "2024-08-16T00:04:23.060Z",
"request": "request_9afca7fa43d44271b4119326de5972ee"
}
Update a webhook
Updates a webhook
object with values passed in. Any parameters not provided are left unchanged.
Parameters
- Name
events
- Type
- string array
- Required
- Required
- Description
The names of the events that the webhook will listen for. All events are listed here. You are able to include
'*'
to listen to all events.
- Name
url
- Type
- string
- Required
- Required
- Description
The HTTP URL endpoint that Sphere will send notifications to upon events triggering.
- Name
active
- Type
- boolean
- Description
Whether the webhook is actively propagating events or not.
- Name
name
- Type
- string
- Description
A name for the webhook. Max length (500).
- Name
description
- Type
- string
- Description
An description for the webhook. Max length (500).
Request
curl https://api.spherepay.co/v1/webhook/webhook_dab187e460e54595a76f66d38b0ee624 \
-H "Authorization: Bearer secret_72c3342954dd4825ad9c2eeb01890ca9" \
-H "Content-Type: application/json" \
-d "{
\"events\": [\"bankAccount.create\", \"wallet.create\"],
\"url\": \"https://example.com/webhook\",
\"active\": "false"
}"
Response
{
"ok": true,
"object": "object",
"statusCode": 200,
"error": null,
"message": "success",
"data": {
"webhook": {
"id": "webhook_dab187e460e54595a76f66d38b0ee624",
"name": "Example Webhook",
"description": "An example webhook",
"active": false,
"deliveryRate": "0",
"status": "failing",
"events": [
"bankAccount.create",
"wallet.create"
],
"url": "https://example.com/webhook",
"secret": "secret_cb8dedcf79a84b04b163ec74c7146481",
"updated": "2024-08-16T01:27:11.101Z",
"created": "2024-08-15T17:55:57.879Z"
}
},
"ts": "2024-08-16T01:27:11.111Z",
"request": "request_5949bacfc8644f2e989822dab1cead19"
}
Delete a webhook
Deletes a webhook
by id
.
Request
curl -X DELETE https://api.spherepay.co/v1/webhook/webhook_dab187e460e54595a76f66d38b0ee624 \
-H "Authorization: Bearer {token}"
Response
{
"ok": true,
"object": "object",
"statusCode": 200,
"error": null,
"message": "success",
"data": {
"webhook": {
"id": "webhook_dab187e460e54595a76f66d38b0ee624",
"name": "Example Webhook",
"description": "An example webhook",
"active": false,
"deliveryRate": "0",
"status": "failing",
"events": [
"bankAccount.create",
"wallet.create"
],
"url": "https://example.com/webhook",
"secret": "secret_cb8dedcf79a84b04b163ec74c7146481",
"updated": "2024-08-16T01:31:39.162Z",
"created": "2024-08-15T17:55:57.879Z"
}
},
"ts": "2024-08-16T01:31:39.173Z",
"request": "request_9b1b7b882a9d4947bcecfb68aedc6263"
}
List all webhooks
This endpoint allows you to retrieve all your webhooks.
Request
curl -G https://api.spherepay.co/v1/webhook \
-H "Authorization: Bearer {token}"
Response
{
"ok": true,
"object": "object",
"statusCode": 200,
"error": null,
"message": "success",
"request": "request_ce7b19b624d549398b1e4e8215603688",
"data": {
"webhooks": [
{
"id": "webhook_7db05ba2124f4efa9a62d73df45c74ee",
"name": "Example Webhook",
"description": "An example webhook",
"active": true,
"health": "healthy",
"events": [
"bankAccount.create",
"wallet.create"
],
"url": "https://example.com/webhook",
"signingSecret": "secret_27e6147edccc4fa7b5012bc59ab3dd96",
"created": "2019-01-01T00:00:00Z",
"updated": "2019-01-01T00:00:00Z"
},
{
"id": "webhook_4c2e18186a7c4a57a927d68cb5d6fcf1"
// ...
}
]
}
}