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: A unique identifier for the object.

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 transfer 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: transfer.cancelled
Description: Whenever the transfer status has been set to cancelled, after a transfer has been soft deleted.

Name: transfer.create
Description: Whenever a new transfer is created.

Name: transfer.failed
Description: Whenever the transfer status has been set to failed, after a transfer has been cancelled.

Name: transfer.funded
Description: Whenever the transfer funding object has received funds.

Name: transfer.pending
Description: Whenever the transfer is awaiting funds.

Name: transfer.processing
Description: Whenever the transfer has been submitted and is processing..

Name: transfer.refunded
Description: Whenever the transfer has been refunded.

Name: transfer.successful
Description: Whenever the transfer 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.