Skip to main content

Webhook Events

All available webhook event types and when they're triggered.

Order Events​

order.created​

Triggered when an order is created and the intent is signaled on-chain.

{
  "id": "evt_abc123",
  "type": "order.created",
  "timestamp": "2024-01-15T10:00:00.000Z",
  "data": {
    "session": { ... },
    "order": {
      "id": "ord_xyz789",
      "status": "SIGNAL_MINED",
      "intentHash": "0x1234...",
      "signalTx": "0xabcd...",
      "paymentPlatform": "venmo",
      "fiatCurrency": "USD",
      "amountUsdc": "50.00",
      "conversionRate": "1.00",
      ...
    }
  }
}

Use cases:

  • Track that a user has started a payment
  • Update order status in your database

order.payment_sent​

Triggered when the user indicates they've sent the fiat payment.

{
  "id": "evt_def456",
  "type": "order.payment_sent",
  "timestamp": "2024-01-15T10:05:00.000Z",
  "data": {
    "session": { ... },
    "order": {
      "id": "ord_xyz789",
      "status": "PAYMENT_SENT",
      ...
    }
  }
}

Use cases:

  • Show "payment pending verification" status to user
  • Start a timer for expected verification

order.fulfilled​

Triggered when the payment is verified and USDC is transferred to your wallet.

{
  "id": "evt_ghi789",
  "type": "order.fulfilled",
  "timestamp": "2024-01-15T10:10:00.000Z",
  "data": {
    "session": { ... },
    "order": {
      "id": "ord_xyz789",
      "status": "FULFILLED",
      "fulfillTx": "0x5678...",
      ...
    },
    "txHash": "0x5678..."
  }
}

Use cases:

  • Fulfill the customer's order
  • Send confirmation email
  • Update inventory
  • Record transaction in accounting

order.failed​

Triggered when payment verification or on-chain fulfillment fails.

{
  "id": "evt_jkl012",
  "type": "order.failed",
  "timestamp": "2024-01-15T10:15:00.000Z",
  "data": {
    "session": { ... },
    "order": {
      "id": "ord_xyz789",
      "status": "FAILED",
      "errorCode": "PROOF_INVALID",
      "errorMessage": "Payment proof validation failed",
      ...
    },
    "error": {
      "code": "PROOF_INVALID",
      "message": "Payment proof validation failed"
    }
  }
}

Error codes:

  • PROOF_INVALID - The payment proof couldn't be verified
  • PROOF_EXPIRED - The proof timestamp was too old
  • FULFILL_TIMEOUT - Transaction timed out
  • FULFILL_REVERTED - On-chain transaction reverted
  • RPC_ERROR - Blockchain RPC error

Use cases:

  • Notify user of failure
  • Allow retry if applicable
  • Log for debugging

order.expired​

Triggered when an order expires before completion.

{
  "id": "evt_mno345",
  "type": "order.expired",
  "timestamp": "2024-01-15T11:00:00.000Z",
  "data": {
    "session": { ... },
    "order": {
      "id": "ord_xyz789",
      "status": "EXPIRED",
      ...
    }
  }
}

Use cases:

  • Release reserved inventory
  • Update order status
  • Notify user session expired

Session Events​

session.started​

Triggered when a user begins a checkout session.

{
  "id": "evt_pqr678",
  "type": "session.started",
  "timestamp": "2024-01-15T09:55:00.000Z",
  "data": {
    "session": {
      "id": "sess_abc123",
      "status": "ACTIVE",
      "selectedPaymentPlatform": "venmo",
      ...
    }
  }
}

session.completed​

Triggered when a checkout session is completed successfully.

{
  "id": "evt_stu901",
  "type": "session.completed",
  "timestamp": "2024-01-15T10:10:00.000Z",
  "data": {
    "session": {
      "id": "sess_abc123",
      "status": "COMPLETED",
      ...
    },
    "order": { ... }
  }
}

session.abandoned​

Triggered when a user abandons the checkout without completing.

{
  "id": "evt_vwx234",
  "type": "session.abandoned",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "data": {
    "session": {
      "id": "sess_abc123",
      "status": "EXPIRED",
      ...
    }
  }
}

Use cases:

  • Send cart abandonment email
  • Analytics tracking