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

Was this page helpful?