Notifications

Get notified when payments complete via polling or webhooks.

Methods

Method	Description	Returns
notify	Check payment status or handle webhooks	`{ allowed: boolean }` or handler
endpoints.create	Create a webhook endpoint	Endpoint
endpoints.list	List all webhook endpoints	Endpoint[]
endpoints.update	Update a webhook endpoint	Endpoint
endpoints.rotateSecret	Rotate endpoint secret	Endpoint

notify

Type (parameters: { mode: "check"; accessToken: string; customerID: string; productID: string }) => Promise<{ allowed: boolean }>

Type (parameters: { mode: "webhook"; secret: string; handler: (event: WebhookEvent) => Promise<void> }) => RequestHandler

Check payment status via polling or create a webhook handler.

// Check mode - poll the API
const { data } = await notify({
  mode: "check",
  accessToken: "sk-...",
  customerID: "cus_01ABC123",
  productID: "prd_01DEF456"
})

if (data?.allowed) {
  // Customer has paid, grant access
}

// Webhook mode - receive real-time notifications
export const handler = notify({
  mode: "webhook",
  secret: process.env.WEBHOOK_SECRET!,
  handler: async (event) => {
    if (event.type === "payment.succeeded") {
      const { customer, payment } = event.payload
      
      await db.orders.update({
        where: { txHash: payment.txHash },
        data: { status: "paid" }
      })
    }
  }
})

endpoints.create

Type (parameters: { name: string; url: string; events: string[] }) => Promise<Endpoint>

Create a new webhook endpoint.

const endpoint = await stackup.webhook.endpoints.create({
  name: "My Webhook",
  url: "https://example.com/webhooks",
  events: ["payment.succeeded"]
})

// Save the secret
console.log("Secret:", endpoint.data.secret)

endpoints.list

Type () => Promise<Endpoint[]>

List all webhook endpoints for the current workspace.

const endpoints = await stackup.webhook.endpoints.list()

endpoints.update

Type (parameters: { id: string; name?: string; url?: string; events?: string[]; status?: "active" | "paused" }) => Promise<Endpoint>

Update an existing webhook endpoint.

await stackup.webhook.endpoints.update({
  id: endpoint.data.id,
  status: "paused"
})

endpoints.rotateSecret

Type (parameters: { id: string }) => Promise<Endpoint>

Rotate the signing secret for a webhook endpoint.

await stackup.webhook.endpoints.rotateSecret({ id: endpoint.data.id })

Event Types

Event	Description
`payment.succeeded`	Payment completed successfully

Payload Format

{
  "type": "payment.succeeded",
  "payload": {
    "customer": {
      "walletAddress": "0x...",
      "email": "user@example.com",
      "name": "John Doe"
    },
    "payment": {
      "status": "succeeded",
      "amount": "1000000",
      "tokenAddress": "0x...",
      "txHash": "0x...",
      "blockNumber": 12345678,
      "productID": "prd_..."
    }
  }
}

Security

Webhooks are signed with HMAC-SHA256. The SDK automatically verifies signatures with a default tolerance of 5 minutes.

Retry Behavior

Failed deliveries retry up to 3 times with delays: immediate, 5 minutes, 30 minutes.

Types

Endpoint

Property	Type	Description
id	string	Unique identifier
workspaceID	string	Parent workspace
name	string	Endpoint display name
url	string	Destination URL
secret	string	Signing secret (whsec_...)
events	string[]	Enabled event types
status	"active" \| "paused"	Delivery status
timeCreated	Date	Creation timestamp
timeUpdated	Date	Last modification

WebhookEvent

Property	Type	Description
type	"payment.succeeded"	Event name
payload	WebhookEventPayload	Event data

WebhookEventPayload

Property	Type	Description
customer	WebhookCustomer	Customer info
payment	WebhookPayment	Payment info

WebhookCustomer

Property	Type	Description
walletAddress	string	Customer wallet address (0x...)
email	string \| null	Customer email
name	string \| null	Customer name
externalID	string \| null	External identifier

WebhookPayment

Property	Type	Description
status	"succeeded" \| "failed"	Payment status
amount	string	Amount in token's smallest unit
tokenAddress	string \| null	Token contract address
txHash	string	Transaction hash (0x...)
blockNumber	number	Block number
productID	string \| null	Purchased product ID