Notifications

Get notified when payments complete via webhooks.

Methods

Method	Description	Returns
notify	Create a webhook handler	`RequestHandler`

notify

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

Create a webhook handler to receive real-time payment notifications.

export const handler = notify({
  secret: process.env.WEBHOOK_SECRET!,
  handler: async (event) => {
    if (event.type === "payment.succeeded") {
      const { payment } = event.payload
      
      await db.orders.update({
        where: { txHash: payment.txHash },
        data: { status: "paid" }
      })
    }
  }
})

Event Types

Event	Description
`payment.succeeded`	Payment completed successfully

Payload Format

{
  "type": "payment.succeeded",
  "payload": {
    "payment": {
      "status": "succeeded",
      "amount": "1000000",
      "tokenAddress": "0x...",
      "txHash": "0x...",
      "blockNumber": 12345678,
      "productID": "prd_..."
    }
  }
}

Security

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

Manual Verification

For manual verification, webhooks include these headers:

Header	Description
`x-webhook-timestamp`	Unix timestamp (seconds) when the webhook was sent
`x-webhook-signature`	HMAC-SHA256 signature prefixed with `sha256=`

The signature is computed over {timestamp}.{payload} where payload is the raw request body.

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
payment	WebhookPayment	Payment info

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

Errors

A list of errors that can be returned by the Notifications API.