An event is when something interesting happens in your Sphere account.
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.
Let's look at an example event object. Don't worry about the length.
(It's mostly the data for the specific event (here, payment.successful) being passed back.)
The event object
{
"id": "event_56c98d7fb4e64f9b867b4dc8997c0b13",
"name": "payment.successful",
"data": {
"payment": {
"id": "payment_d81efad665f649e2b0ea8b959feb6ee9",
"type": "paymentLink",
"status": "pending",
"created": "2023-05-04T16:10:12.068Z",
"invoice": null,
"updated": "2023-05-04T16:10:12.068Z",
"customer": {
"id": "customer_2b2990e19b1a43c682d581e5e31aeada",
"created": "2023-05-04T16:10:11.714Z",
"updated": "2023-05-04T16:10:11.714Z",
"delinquent": false,
"personalInfo": {
"id": "personalInfo_292e8febad504f6d891be5112e6a81ee",
"email": "[email protected]",
"address": {
"geo": {
"lat": null,
"long": null
},
"city": "",
"line1": "",
"line2": "",
"state": "",
"country": "",
"created": "2023-05-04T16:10:11.697Z",
"updated": "2023-05-04T16:10:11.697Z",
"postalCode": ""
},
"created": "2023-05-04T16:10:11.706Z",
"updated": "2023-05-04T16:10:11.706Z",
"lastName": "",
"firstName": "adsg",
"phoneNumber": ""
},
"solanaPubKey": "J3vUP1J72AjFKYUcFjo4oUTTv5ayrv7GhbBZQo7so1qw"
},
"transport": {
"solana": {
"id": "solanaTransport_8414e27703a646979b78f6c2d6ffd37d",
"tx": "AqnsLfRylrNsoRhJb3d5x5cyDRXTWZ+IUnwzzhDLygq77CzgCH3szqlUulpi7W+J/cIY3EA0vQqDKb8O6vlFswMAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAgAIAAwfZ99UgA2OCG0K8V2X8J6seRpJjjiDYu4HNDfzNeynCv/1WTOgIWp7DossY72B/JKiCKnGQ8CpzVCkVMlSGWpomAcj9bZyMLgZh+jk790qmQJ7CsTvks74Rd9hr/nPBwuN/9w4Aabb+dc+rWdp/HMrSUoPCom6JakfRiZGy++C4+QMGRm/lIRcy/+ytunLDm+e8jOW7xfcSayxDmzpAAAAAOI9idf3s5X8gY3HjwlqbxUiZ5cM/dze17aIY+/DCpAwGp9UXGSxcUSGMyUw9SvF/WNruCJuh/UTj29mKAAAAAMYPyOTUdVV14xvrQVMTp4tJDplivWZbdn7I1UBjx7bIAgQABQLAXBUABRAHAAABAQgJAgMKAwoDCwYMPHFhpQibvdDoIAAAAGhhc2hfNzVjMGJkOWFmN2MzNGIxMjgwNjg2N2I0NjBhmFMAAAAAAADghgEAAAAAAAED84lUVVPga8IpchNrNiIwclxV/+xpGiuS7d+jn4m8cQELBRIUBRMH",
"hash": "hash_75c0bd9af7c34b12806867b460a",
"swapTx": {},
"created": "2023-05-04T16:10:11.709Z",
"updated": "2023-05-04T16:10:12.059Z",
"solanaEvent": null
}
},
"paymentLink": {
"id": "paymentLink_1aad1e1f6d7942d5b861ed32a46156e0",
"url": "http://localhost:3000/pay/paymentLink_1aad1e1f6d7942d5b861ed32a46156e0",
"meta": {},
"name": "",
"created": "2023-05-04T16:09:56.990Z",
"failUrl": "",
"updated": "2023-05-04T16:09:56.990Z",
"features": {
"requiresName": true,
"requiresEmail": true,
"requiresShippingDetails": false
},
"lineItems": [
{
"id": "lineItem_b6416dd7d91c429f80ad491260dc93e4",
"name": "lineItem_b6416dd7d91c429f80ad491260dc93e4",
"price": {
"id": "price_d54154545feb4aa0b3da5013c35b81c3",
"meta": {},
"name": null,
"type": "oneTime",
"tiers": [],
"active": true,
"created": "2023-05-04T16:09:44.407Z",
"network": null,
"product": {
"id": "product_38f38fbef96848888659cac45acdc0eb",
"meta": {},
"name": "asdg",
"tags": [],
"images": [],
"prices": [],
"created": "2023-05-04T16:09:44.455Z",
"updated": "2023-05-04T16:09:44.455Z",
"description": "asdgasdg"
},
"updated": "2023-05-04T16:09:44.455Z",
"currency": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
"tierType": null,
"lookupKey": null,
"recurring": {
"interval": null,
"usageType": null,
"defaultLength": null,
"intervalCount": null,
"usageAggregation": null
},
"unitAmount": "21400",
"description": null,
"taxBehavior": "exclusive",
"billingScheme": "perUnit",
"currencyOptions": [],
"customUnitAmount": {
"max": null,
"min": null,
"preset": null
},
"unitAmountDecimal": 0.0214
},
"created": "2023-05-04T16:09:56.990Z",
"updated": "2023-05-04T16:09:56.990Z",
"quantity": 1,
"description": "",
"quantityMutable": false
}
],
"successUrl": "",
"application": {
"id": "application_bb6754ed346341b19320ad69acdba21e",
"name": "default",
"user": {},
"image": null,
"created": "2023-05-04T16:08:57.285Z",
"updated": "2023-05-04T16:08:57.285Z",
"nickname": null,
"isDefault": true,
"proxySolanaPubKey": null
},
"description": ""
},
"personalInfo": {
"id": "personalInfo_292e8febad504f6d891be5112e6a81ee",
"email": "[email protected]",
"address": {
"geo": {
"lat": null,
"long": null
},
"city": "",
"line1": "",
"line2": "",
"state": "",
"country": "",
"created": "2023-05-04T16:10:11.697Z",
"updated": "2023-05-04T16:10:11.697Z",
"postalCode": ""
},
"created": "2023-05-04T16:10:11.706Z",
"updated": "2023-05-04T16:10:11.706Z",
"lastName": "",
"firstName": "adsg",
"phoneNumber": ""
},
"transactions": []
}
},
"mock": true,
"updated": "2021-01-01T00:00:00.000Z",
"created": "2021-01-01T00:00:00.000Z"
}
As you can see, the event records all of the relevant information about the resource it is attached to.
However, if we drill down into the object, there are just a couple of key fields:
{
"id": "event_56c98d7fb4e64f9b867b4dc8997c0b13",
"name": "payment.successful",
"data": {
"..."
},
"mock": true,
"created": "2021-01-01T00:00:00.000Z",
"updated": "2021-01-01T00:00:00.000Z"
}
id: a string that Sphere auto-generates for you upon creation.
name: the particular event that occurred.
data: the relevant information about the resource the event is associated with.
mock: a boolean that indicates whether the event was a test generated by the mock API.
updated and created are string timestamps following the JavaScript date time string format that describe when the product was last updated and when it was created.
Available Events
enum EVENT_NAMES {
// Address
CREATE_ADDRESS = "address.create",
// Alert
CREATE_ALERT = "alert.create",
UPDATE_ALERT = "alert.update",
// Tax Rate
CREATE_TAX_RATE = "taxRate.create",
DELETE_TAX_RATE = "taxRate.delete",
UPDATE_TAX_RATE = "taxRate.update",
// Escrow
CREATE_ESCROW = "escrow.create",
UPDATE_ESCROW = "escrow.update",
DISBURSE_ESCROW = "escrow.disburse",
// ApiKey
CREATE_API_KEY = "apiKey.create",
UPDATE_API_KEY = "apiKey.update",
DELETE_API_KEY = "apiKey.delete",
// Customer
CREATE_CUSTOMER = "customer.create",
UPDATE_CUSTOMER = "customer.update",
// EMAIL
CREATE_EMAIL = "email.create",
// FILE
CREATE_FILE = "file.create",
// Impression
CREATE_IMPRESSION = "impression.create",
UPDATE_IMPRESSION = "impression.update",
// Metric
UPDATE_METRIC = "metric.update",
// Payment
PENDING_PAYMENT = "payment.pending",
CANCELLED_PAYMENT = "payment.cancelled",
SUCCESSFUL_PAYMENT = "payment.successful",
INCOMPLETE_PAYMENT = "payment.incomplete",
UPDATE_PAYMENT = "payment.update",
FAILED_PAYMENT = "payment.failed",
// PaymentLink
CREATE_PAYMENT_LINK = "paymentLink.create",
DELETE_PAYMENT_LINK = "paymentLink.delete",
UPDATE_PAYMENT_LINK = "paymentLink.update",
// Price
CREATE_PRICE = "price.create",
DELETE_PRICE = "price.delete",
UPDATE_PRICE = "price.update",
// Product
CREATE_PRODUCT = "product.create",
DELETE_PRODUCT = "product.delete",
UPDATE_PRODUCT = "product.update",
// Refund
PENDING_REFUND = "refund.pending",
SUCCESSFUL_REFUND = "refund.successful",
INCOMPLETE_REFUND = "refund.incomplete",
FAILED_REFUND = "refund.failed",
UPDATE_REFUND = "refund.update",
// Transaction
CREATE_TRANSACTION = "transaction.create",
UPDATE_TRANSACTION = "transaction.update",
// Subscription
BILL_SUBSCRIPTION = "subscription.bill",
APPROVE_SUBSCRIPTION = "subscription.approve",
LOW_BALANCE_ESCROWED_SUBSCRIPTION = "subscription.escrowed.low_balance",
LOW_BALANCE_DELEGATED_SUBSCRIPTION = "subscription.delegated.low_balance",
INSUFFICIENT_DELEGATED_BALANCE_SUBSCRIPTION = "subscription.delegated.insufficient_balance",
INSUFFICIENT_DELEGATED_APPROVED_SUBSCRIPTION = "subscription.delegated.insufficient_approved",
INSUFFICIENT_ESCROWED_BALANCE = "subscription.escrowed.insufficient_balance",
REDELEGATED_SUBSCRIPTION = "subscription.delegated.redelegated",
CREATE_SUBSCRIPTION = "subscription.create",
PAST_DUE_SUBSCRIPTION = "subscription.pastDue",
DELETE_SUBSCRIPTION = "subscription.delete",
UPDATE_SUBSCRIPTION = "subscription.update",
// Usage Record
CREATE_USAGE_RECORD = "usageRecord.create",
// Webhook
CREATE_WEBHOOK = "webhook.create",
DELETE_WEBHOOK = "webhook.delete",
UPDATE_WEBHOOK = "webhook.update",
// Bank Account
CREATE_BANK_ACCOUNT = "bank_account.create",
DELETE_BANK_ACCOUNT = "bank_account.delete",
UPDATE_BANK_ACCOUNT = "bank_account.update",
// Payout
CREATE_PAYOUT = "payout.create",
DELETE_PAYOUT = "payout.delete",
UPDATE_PAYOUT = "payout.update",
SUCCESSFUL_PAYOUT = "payout.success",
FAILED_PAYOUT = "payout.failed"
}