Setup your webhook

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.

The average response time of Sphere webhook requests is under 5000ms.

Webhook Signatures

A webhook signature is a security measure which allows you to verify the integrity and authenticity of the data you're receiving, using hash-based message authentication code (HMAC).

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.

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

Webhook Event Sequencing

Webhook events are guaranteed to be sent at least once. However, due to the nature of the webhook system, events may be sent out of order.

This means that you may receive notifications in an unexpected order.

For this reason, we recommend that you design your implementation in a way that does not rely on the order that events are received.

Create a Webhook

To start receiving webhook notifications, you can use our Webhook API to create a webhook by specifying the URL and the events you want to receive.

For the full API specification, see the Sphere API Reference.

Request Example

{
    "name": "Example Webhook",
    "description": "An example webhook",
    "url": "https://example.com/webhook",
    "events": ["bankAccount.create", "wallet.create"]
}

Response Example

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