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.

Endpoints

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, or dead.
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, and 1 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"
}

POST/v1/webhook

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

POST

/v1/webhook

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"
}

GET/v1/webhook/:id

Retrieve a webhook

Retrieves a webhook object by id.

Request

GET

/v1/webook/:id

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"
}

POST/v1/webhook/:id

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

POST

/v1/webhook/:id

curl https://api.spherepay.co/v1/webhook/webhook_dab187e460e54595a76f66d38b0ee624 \
  -X POST \
  -H "Authorization: Bearer {token}" \
  -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/v1/webhook/:id

Delete a webhook

Deletes a webhook by id.

Request

DELETE

/v1/webook/:id

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"
}

GET/v1/webhook

List all webhooks

This endpoint allows you to retrieve all your webhooks.

Request

GET

/v1/webhook

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"
        // ...
      }
    ]
  }
}