Webhooks allow you to propagate data to your server when something interesting happens.

You can use webhooks to listen for events on your Sphere account and get automatically notified when key events, such as a successful purchase, confirmed bank 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 <1000ms.

The webhook object

{
  "id": "webhook_8ed61f88927a47dba51ad09439925f71",
  "created": "2021-01-01T00:00:00.000Z",
  "events": [
    "price.create",
    "product.create",
    "payment.successful"
  ],
  "secret": "secret_3f523ea79f654f8caecf1ffe7b9abb3c",
  "updated": "2021-01-01T00:00:00.000Z",
  "url": "https://api.your-api.co/v1/consume_events"
}

id: a unique string identifier for the object. Auto-generated by Sphere upon creation.

name: a string of max length 500 for what you'll call your webhook, hidden from customers.

description: a string of max length 500 that describes your webhook, hidden from customers.

events: a list of event objects that your webhook is listening for.

url: the string HTTP URL endpoint that Sphere will send notifications to upon events triggering.

secret: the string SHA265 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.

active: a boolean which denotes whether your webhook should receive messages from Sphere. Inactive webhooks still contribute to your 10 webhook limit.

updated and created are string timestamps following the JavaScript date time string format that describe when the webhook was last updated and when it was created.