Skip to main content

Webhook Payloads

Canonical Structure​

interface WebhookPayload {
  id: string;
  type: string;
  timestamp: string;
  data: {
    order: CheckoutOrder | null;
    payment: CheckoutPayment | null;
    paymentBridge: Record<string, unknown> | null;
  };
}

data.order​

CheckoutOrder is present for order lifecycle events and usually includes:

  • id
  • merchantId
  • status
  • requestedUsdcAmount
  • remainingUsdcAmount
  • destinationAddress
  • destinationToken
  • destinationChainId
  • metadata

data.payment​

CheckoutPayment may be present for fulfillment/payout-related events.

Useful fields:

  • id
  • orderId
  • rail
  • paymentAmount
  • netSettledUsdcAmount
  • fulfillTransaction

Example​

{
  "id": "evt_abc123",
  "type": "PAYMENT_SETTLED",
  "timestamp": "2026-04-03T10:00:00.000Z",
  "data": {
    "order": {
      "id": "ord_123",
      "merchantId": "merchant_123",
      "status": "FULFILLED",
      "requestedUsdcAmount": "50.00",
      "remainingUsdcAmount": "0.00",
      "destinationAddress": "0x742d...",
      "destinationToken": "USDC",
      "destinationChainId": "8453"
    },
    "payment": {
      "id": "pay_123",
      "orderId": "ord_123",
      "rail": "venmo",
      "paymentAmount": "50.00",
      "netSettledUsdcAmount": "49.50",
      "fulfillTransaction": "0xabc..."
    },
    "paymentBridge": null
  }
}

Bridge Event Payloads​

For PAYMENT_BRIDGE_PENDING, PAYMENT_BRIDGE_SUBMITTED, PAYMENT_BRIDGE_COMPLETED, and PAYMENT_BRIDGE_FAILED, data.paymentBridge includes bridge state and destination transfer metadata.