Events

When something interesting (e.g., a successful payment) occurs on your Sphere account, we create an event object that you can listen for through a webhook.

It is not uncommon for a single API request or key action on your platform to create multiple events. For example, when someone purchases a recurring product (e.g., a subscription) from a payment link or invoice, a subscription.created and payment.successful event will be created.

All event types can be found here, and all can be used in webhooks.

Endpoints

GET

/v1/event/:id

The Event object

Properties

Name
id
Type
string
Description
Unique identifier for the event. Auto-generated by Sphere upon creation.
Name
name
Type
string
Description
The name of the event. List of events can be found here.
Name
data
Type
object
Description
The data associated with the event. The data is dependent on the name of the event.
Name
webhookRecords
Type
object array
Description
A list of objects associated with the event.
- Name
  requestIds
  Type
  string array
  Description
  The ids of the egress requests that triggered the webhook.
- Name
  webhook
  Type
  object
  Description
  The webhook object that was triggered by the egress request. Refer to the Webhook object for more details.
Name
mock
Type
boolean
Description
Whether the event is a mock event. False by default. Only true when payout requests set the mock field to true.
Name
updated
Type
string
Description
Datetime of when the event was last updated.
Name
created
Type
number
Description
Datetime of when the event was created.

Event Object

{
  "id": "event_d9703d1368074a5c8abde749ac04a3c1",
  "name": "wallet.create",
  "data": {
    "wallet": {
      "id": "wallet_925402799af140fb85ab98ce4330e417",
      "mock": false,
      "risk": null,
      "owner": "merchant",
      "signed": false,
      "address": "5ycZq7CQPahECKzXWAxbjghkv2nM81zLYym9SWGZxdLj",
      "created": "2024-08-15T21:57:45.432Z",
      "deleted": null,
      "network": "sol",
      "primary": false,
      "updated": "2024-08-15T21:57:45.432Z",
      "customer": null,
      "exported": null,
      "feePayer": false,
      "nickname": null,
      "lookupKey": null
    }
  },
  "webhookRecords": [
    {
      "requestIds": ["request_fefa2ff6169e45efa74b022e0fe868fb"],
      "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-15T21:57:20.144Z",
        "created": "2024-08-15T17:55:57.879Z"
      }
    }
  ],
  "mock": false,
  "updated": "2024-08-15T21:57:45.467Z",
  "created": "2024-08-15T21:57:45.467Z"
}

GET/v1/event/:id

Retrieve an event

Retrieves an event by id, most often retrieved through a webhook payload or through the dashboard.

Request

GET

/v1/event/:id

curl -G https://api.spherepay.co/v1/event/event_d9703d1368074a5c8abde749ac04a3c1 \
  -H "Authorization: Bearer {token}"

Response

{
  "ok": true,
  "object": "object",
  "statusCode": 200,
  "error": null,
  "message": "success",
  "data": {
    "event": {
      "id": "event_d9703d1368074a5c8abde749ac04a3c1",
      "name": "wallet.create",
      "data": {
        "wallet": {
          "id": "wallet_925402799af140fb85ab98ce4330e417",
          "mock": false,
          "risk": null,
          "owner": "merchant",
          "signed": false,
          "address": "5ycZq7CQPahECKzXWAxbjghkv2nM81zLYym9SWGZxdLj",
          "created": "2024-08-15T21:57:45.432Z",
          "deleted": null,
          "network": "sol",
          "primary": false,
          "updated": "2024-08-15T21:57:45.432Z",
          "customer": null,
          "exported": null,
          "feePayer": false,
          "nickname": null,
          "lookupKey": null
        }
      },
      "webhookRecords": [
        {
          "requestIds": ["request_fefa2ff6169e45efa74b022e0fe868fb"],
          "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-15T21:57:20.144Z",
            "created": "2024-08-15T17:55:57.879Z"
          }
        }
      ],
      "mock": false,
      "updated": "2024-08-15T21:57:45.467Z",
      "created": "2024-08-15T21:57:45.467Z"
    }
  },
  "ts": "2024-08-15T21:58:10.480Z",
  "request": "request_fc713225d6a74b7db73f3e290e7db2e4"
}

Types of events

Event

Name
address.create
Description
Whenever a new address is created.
Name
alert.create
Description
Whenever a new alert is created.
Name
alert.update
Description
Whenever an existing alert is updated.
Name
apiKey.create
Description
Whenever a new API key is created.
Name
apiKey.delete
Description
Whenever an API key is deleted.
Name
apiKey.update
Description
Whenever an existing API key is updated.
Name
application.update
Description
Whenever an existing application is updated.
Name
bankAccount.create
Description
Whenever a new bank account is created.
Name
bankAccount.update
Description
Whenever an existing bank account is updated.
Name
coupon.create
Description
Whenever a new coupon is created.
Name
coupon.delete
Description
Whenever a coupon is deleted.
Name
coupon.update
Description
Whenever an existing coupon is updated.
Name
customer.create
Description
Whenever a new customer is created.
Name
customer.delete
Description
Whenever a customer is deleted.
Name
customer.update
Description
Whhenever an existing customer is updated.
Name
customer.kyc.pending
Description
Whenever a customer has started the Sphere KYC flow.
Name
customer.kyc.rejected
Description
Whenever a customer has been rejected
Name
customer.kyc.successful
Description
Whenever a customer has successfully completed the Sphere KYC flow.
Name
customer.kyc.additionalReviewRequired
Description
Whenever a customer has completed the Sphere KYC flow but requires additional review.
Name
customer.tos.pending
Description
Whenever a customer has started the Sphere Terms of Service flow.
Name
customer.tos.successful
Description
Whenever a customer has successfully completed the Sphere Terms of Service flow.
Name
email.create
Description
Whenever a new email is created.
Name
file.create
Description
Whenever a new file is created.
Name
limit.create
Description
Whenever a payment link phase limit is created.
Name
limit.update
Description
Whenever an existing payment link phase limit is updated.
Name
nftDiscount.create
Description
Whenever a new NFT discount is created.
Name
nftDiscount.delete
Description
Whenever a NFT discount is deleted.
Name
nftDiscount.update
Description
Whenever an existing NFT discount is updated.
Name
payment.cancelled
Description
Whenever a payment has been cancelled.
Name
payment.failed
Description
Whenever a payment has failed.
Name
payment.incomplete
Description
Whenever a payment is incomplete.
Name
payment.pending
Description
Whenever a payment is pending.
Name
payment.successful
Description
Whenever a payment is successful.
Name
payment.card.refunded
Description
Whenever a card payment is refunded.
Name
paymentLink.create
Description
Whenever a new payment link is created.
Name
paymentLink.delete
Description
Whenever a payment link is deleted.
Name
paymentLink.update
Description
Whenever an existing payment link is updated.
Name
payout.cancelled
Description
Whenever the payout status has been set to cancelled, after a payout has been soft deleted.
Name
payout.create
Description
Whenever a new payout is created.
Name
payout.failed
Description
Whenever the payout status has been set to failed, after a payout has been cancelled.
Name
payout.funded
Description
Whenever the payout funding object has received funds.
Name
payout.pending
Description
Whenever the payout is awaiting funds.
Name
payout.processing
Description
Whenever the payout has been submitted and is processing..
Name
payout.refunded
Description
Whenever the payout has been refunded.
Name
payout.successful
Description
Whenever the payout has been processed and is successful.
Name
phase.create
Description
Whenever a new payment link phase is created.
Name
phase.update
Description
Whenever an existing payment link phase is updated.
Name
price.create
Description
Whenever a new price is created.
Name
price.delete
Description
Whenever a price is deleted.
Name
price.update
Description
Whenever an existing price is updated.
Name
product.create
Description
Whenever a new product is created.
Name
product.delete
Description
Whenever a product is deleted.
Name
product.update
Description
Whenever an existing product is updated.
Name
promotionCode.create
Description
Whenever a new promotion code is created.
Name
promotionCode.delete
Description
Whenever a promotion code is deleted.
Name
promotionCode.update
Description
Whenever an existing promotion code is updated.
Name
restrictedApiKey.create
Description
Whenever a new restricted API key is created.
Name
restrictedApiKey.delete
Description
Whenever a restricted API key is deleted.
Name
restrictedApiKey.update
Description
Whenever an existing restricted API key is updated.
Name
shippingRate.create
Description
Whenever a new shipping rate is created.
Name
subscription.approve
Description
Whenever the customer has approved or escrowed funds to fund the subscription.
Name
subscription.create
Description
Whenever a new subscription is created, when a customer pays on a paymentLink with a recurring price type.
Name
subscription.cancel
Description
Whenever a subscription's status changes to cancelled.
Name
subscription.pastDue
Description
Whenever a subscription's status changes to pastDue.
Name
subscription.update
Description
Whenever the customer updates the subscription.
Name
subscription.bill
Description
Whenever Sphere attempts to bill the subscription, regardless of if the transaction succeeds or fails.
Name
subscription.bill.retry
Description
Whenever a subscription is in retrry and Sphere attempts to bill it again.
Name
subscription.delegated.insufficientApprovedBalance
Description
Whenever the subscription does not have enough tokens delegated for billing.
Name
subscription.delegated.insufficientBalance
Description
Whenever the delegated token account contains insufficient tokens for billing.
Name
subscription.delegated.lowBalance
Description
Whenever the delegated balance in the subscription is running low.
Name
subscription.delegated.redelegated
Description
Whenever the delegated token account has been redelegated.
Name
subscription.escrowed.insufficientBalance
Description
Whenever the escrowed token account contains insufficient tokens for billing.
Name
subscription.escrowed.lowBalance
Description
Whenever the escrowed balance in the subscription is running low.
Name
taxRate.create
Description
Whenever a new tax rate is created.
Name
taxRate.delete
Description
Whenever a tax rate is deleted.
Name
taxRate.update
Description
Whenever an existing tax rate is updated.
Name
transaction.create
Description
Whenever a new transaction is created.
Name
transaction.update
Description
Whenever an existing transaction is updated.
Name
usageRecord.create
Description
Whenever a new usage record is created.
Name
wallet.create
Description
Whenever a new wallet is created.
Name
webhook.create
Description
Whenever a new webhook is created.
Name
webhook.delete
Description
Whenever a webhook is deleted.
Name
webhook.update
Description
Whenever an existing webhook is updated.