Webhook Details

Webhook Event Types

Each webhook event contains a standardized payload with information about what happened. This guide provides detailed information about each event type.

Common Payload Structure

All webhook events follow the same structure:

{
  "id": "evt_abc123",
  "type": "invoice.created",
  "created": 1699900000,
  "livemode": true,
  "data": { ... }
}

Field	Type	Description
`id`	string	Unique event identifier (format: `evt_` + UUID)
`type`	string	Event type (e.g., `"invoice.created"`)
`created`	integer	Unix timestamp when the event was created
`livemode`	boolean	`true` in production, `false` in sandbox
`data`	object	The affected object (invoice data directly)

Invoice Events

Invoice Created

Triggered when payment is initiated (user clicks pay button).

{
  "id": "evt_abc123",
  "type": "invoice.created",
  "created": 1699900000,
  "livemode": true,
  "data": {
    "paylinkId": "120e3400-e12b-04d4-a716-446417440031",
    "invoiceId": "550e8400-e29b-41d4-a716-446655440000",
    "orgId": "org_def456",
    "chainId": 42161,
    "token": "0xaf88...5831",
    "symbol": "USDC",
    "network": "ARB",
    "paymentType": "ONE_TIME",
    "amount": "0",
    "amountUsd": "0",
    "status": "pending",
    "expiresAt": "2024-11-15T14:00:00.000Z",
    "createdAt": "2024-11-14T14:00:00.000Z",
    "updatedAt": "2024-11-14T14:00:00.000Z",
    "metadata": {},
    "customer": {
      "email": "customer@example.com",
      "clientReferenceId": "cust_123",
      "name": "John Doe"
    }
  }
}

Invoice Overdue

Triggered when payment deadline passes without payment.

{
  "id": "evt_abc123",
  "object": "event",
  "type": "invoice.overdue",
  "created": 1699900000,
  "livemode": true,
  "data": {
    "paylinkId": "120e3400-e12b-04d4-a716-446417440031",
    "invoiceId": "550e8400-e29b-41d4-a716-446655440000",
    "orgId": "org_def456",
    "chainId": 42161,
    "token": "0xaf88...5831",
    "symbol": "USDC",
    "network": "ARB",
    "paymentType": "RECURRING",
    "amount": "0",
    "amountUsd": "0",
    "status": "expired",
    "expiresAt": "2024-11-15T14:00:00.000Z",
    "createdAt": "2024-11-14T14:00:00.000Z",
    "updatedAt": "2024-11-15T14:01:00.000Z",
    "metadata": {},
    "customer": {
      "email": "customer@example.com",
      "clientReferenceId": "cust_123",
      "name": "John Doe"
    }
  }
}

Invoice Cancelled

Triggered when user cancels the invoice or subscription.

{
  "id": "evt_abc123",
  "object": "event",
  "type": "invoice.cancelled",
  "created": 1699900000,
  "livemode": true,
  "data": {
    "paylinkId": "120e3400-e12b-04d4-a716-446417440031",
    "invoiceId": "550e8400-e29b-41d4-a716-446655440000",
    "orgId": "org_def456",
    "chainId": 42161,
    "token": "0xaf88...5831",
    "symbol": "USDC",
    "network": "ARB",
    "paymentType": "RECURRING",
    "amount": "0",
    "amountUsd": "0",
    "status": "cancelled",
    "expiresAt": "2024-11-15T14:00:00.000Z",
    "createdAt": "2024-11-14T14:00:00.000Z",
    "updatedAt": "2024-11-14T15:00:00.000Z",
    "metadata": {},
    "customer": {
      "email": "customer@example.com",
      "clientReferenceId": "cust_123",
      "name": "John Doe"
    }
  }
}

Payment Events

Payment Confirmed

Triggered when payment has received enough blockchain confirmations to be considered final.

{
  "id": "evt_abc123",
  "object": "event",
  "type": "payment.confirmed",
  "created": 1699900000,
  "livemode": true,
  "data": {
    "paylinkId": "120e3400-e12b-04d4-a716-446417440031",
    "invoiceId": "550e8400-e29b-41d4-a716-446655440000",
    "orgId": "org_def456",
    "chainId": 42161,
    "token": "0xaf88...5831",
    "symbol": "USDC",
    "network": "ARB",
    "paymentType": "RECURRING",
    "amount": "1.00",
    "amountUsd": "1.00",
    "status": "confirmed",
    "expiresAt": "2024-11-15T14:00:00.000Z",
    "createdAt": "2024-11-14T14:00:00.000Z",
    "updatedAt": "2024-11-14T15:00:00.000Z",
    "metadata": {},
    "customer": {
      "email": "customer@example.com",
      "clientReferenceId": "cust_123",
      "name": "John Doe"
    }
  }
}

Subscription Events

Subscription Overdue

Triggered when a subscription expires without payment renewal.

{
  "id": "evt_abc123",
  "type": "subscription.overdue",
  "created": 1699900000,
  "livemode": true,
  "data": {
    "subscriptionId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "overdue",
    "expiresAt": "2024-11-15T14:00:00.000Z",
    "recurringInterval": "MONTH",
    "productName": "Premium Plan",
    "orgId": "org_def456",
    "organizationName": "Acme Corp",
    "customerId": "550e8400-e29b-41d4-a716-446655440099",
    "paylinkId": "120e3400-e12b-04d4-a716-446417440031",
    "invoiceId": "550e8400-e29b-41d4-a716-446655440001",
    "chainId": 42161,
    "token": "0xaf88...5831",
    "symbol": "USDC",
    "network": "ARB",
    "paymentType": "RECURRING",
    "amount": "1.00",
    "amountUsd": "1.00",
    "createdAt": "2024-11-01T14:00:00.000Z",
    "updatedAt": "2024-11-15T14:01:00.000Z",
    "metadata": {},
    "customer": {
      "email": "customer@example.com",
      "name": "John Doe"
    }
  }
}

Handling Recurring Customers

When you receive invoice.created for a recurring customer:

Important: Use clientReferenceId or email to identify existing customers:

If clientReferenceId or email already exists in your database → update existing customer (don't create new)
If new → create new customer

The same customer may have multiple invoices over time - always use clientReferenceId or email to identify them.

Object Field Reference

Invoice Object

Field	Type	Description
`paylinkId`	string	Paylink identifier
`invoiceId`	string	Invoice identifier (UUID)
`orgId`	string	Organization ID
`chainId`	integer	Blockchain chain ID
`token`	string	Token contract address
`symbol`	string	Token symbol (e.g., "USDC")
`network`	string	Network name (e.g., "ARB")
`paymentType`	string	`"ONE_TIME"` or `"RECURRING"`
`amount`	string	Amount received (formatted, human-readable, e.g., "1.00")
`amountUsd`	string	Amount in USD equivalent (e.g., "1.00")
`status`	string	Current invoice status
`expiresAt`	string	Expiration timestamp (ISO 8601)
`createdAt`	string	Creation timestamp (ISO 8601)
`updatedAt`	string	Last update timestamp (ISO 8601)
`customerId`	string	Customer identifier (UUID, optional)
`metadata`	object	Custom metadata
`customer`	object	Customer information

Payment Object

Field	Type	Description
`paylinkId`	string	Paylink identifier
`invoiceId`	string	Associated invoice ID
`orgId`	string	Organization ID
`chainId`	integer	Blockchain chain ID
`token`	string	Token contract address
`symbol`	string	Token symbol (e.g., "USDC")
`network`	string	Network name (e.g., "ARB")
`paymentType`	string	`"ONE_TIME"` or `"RECURRING"`
`amount`	string	Amount received (formatted, e.g., "1.00")
`amountUsd`	string	Amount in USD (e.g., "1.00")
`status`	`"confirmed"`	Payment status
`expiresAt`	string	Expiration timestamp
`createdAt`	string	Creation timestamp
`updatedAt`	string	Last update timestamp
`customerId`	string	Customer identifier (UUID, optional)
`metadata`	object	Custom metadata
`customer`	object	Customer information

Customer Object

Field	Type	Description
`email`	string	Customer email address
`clientReferenceId`	string	Your internal customer reference
`name`	string	Customer name (if provided)
`phone`	string	Customer phone (if provided)
`dateOfBirth`	string	Customer dateOfBirth (if provided)
`address`	string	Customer address (if provided)

Subscription Object

Field	Type	Description
`subscriptionId`	string	Subscription identifier (UUID)
`status`	string	Subscription status (e.g., "overdue")
`expiresAt`	string	Expiration timestamp (ISO 8601)
`recurringInterval`	string	Recurring interval (e.g., "MONTH")
`productName`	string	Product/service name
`orgId`	string	Organization ID
`organizationName`	string	Organization name
`customerId`	string	Customer identifier
`paylinkId`	string	Paylink identifier
`invoiceId`	string	Associated invoice ID
`chainId`	integer	Blockchain chain ID
`token`	string	Token contract address
`symbol`	string	Token symbol (e.g., "USDC")
`network`	string	Network name (e.g., "ARB")
`paymentType`	string	`"ONE_TIME"` or `"RECURRING"`
`amount`	string	Amount (formatted, e.g., "1.00")
`amountUsd`	string	Amount in USD (e.g., "1.00")
`createdAt`	string	Subscription creation timestamp
`updatedAt`	string	Last update timestamp
`metadata`	object	Custom metadata
`customer`	object	Customer information

Webhook Details

On this page