Webhooks

{
  "id": "evt_1234567890abcdef",
  "object": "event",
  "type": "payment.settled",
  "created_at": "2024-01-15T12:30:00Z",
  "data": {
    "object": {
      "id": "tz4a98xxat96iws9zmbrgj3a",
      "object": "payment",
      "status": "settled",
      "method": "DIRECT",
      "amount": "5000000",
      "amount_paid": "5000000",
      "currency": "USD",
      "detected_token": "USDC",
      "detected_token_address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "detected_chain": "eip155:1",
      "token_amount": "5000000",
      "token_amount_decimal": "5",
      "on_chain_id": "0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b",
      "deposit_address": "0x5fbdb2315678afecb367f032d93f642f64180aa3",
      "deploy_tx_hash": "0x8a9c67b2d1e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9",
      "payer_addresses": ["0x742d35Cc6634C0532925a3b844Bc9e7595f8fE21"],
      "transactions": [
        {
          "tx_hash": "0xabc...",
          "from": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE21",
          "amount": "5000000",
          "token": "USDC",
          "network": "ethereum",
          "block_number": "12345678",
          "is_funding": true
        }
      ],
      "non_funding_transactions_count": 0,
      "created_at": "2024-01-15T12:00:00Z",
      "updated_at": "2024-01-15T12:30:00Z"
    }
  }
}

{
  "id": "evt_abcdef1234567890",
  "object": "event",
  "type": "payment.escrow_confirmed",
  "created_at": "2024-01-15T14:00:00Z",
  "data": {
    "object": {
      "id": "tz4a98xxat96iws9zmbrgj3a",
      "object": "payment",
      "status": "escrow_confirmed",
      "method": "TWO_STEP",
      "amount": "5000000",
      "amount_paid": "5000000",
      "currency": "USD",
      "detected_token": "USDC",
      "detected_token_address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "detected_chain": "eip155:1",
      "token_amount": "5000000",
      "token_amount_decimal": "5",
      "on_chain_id": "0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b",
      "deposit_address": "0x5fbdb2315678afecb367f032d93f642f64180aa3",
      "deploy_tx_hash": "0x8a9c67b2d1e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9",
      "payer_addresses": ["0x742d35Cc6634C0532925a3b844Bc9e7595f8fE21"],
      "transactions": [
        {
          "tx_hash": "0xdef...",
          "from": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE21",
          "amount": "5000000",
          "token": "USDC",
          "network": "ethereum",
          "block_number": "12346789",
          "is_funding": true
        }
      ],
      "non_funding_transactions_count": 0,
      "created_at": "2024-01-15T12:30:00Z",
      "updated_at": "2024-01-15T14:00:00Z"
    }
  }
}

{
  "id": "evt_fedcba0987654321",
  "object": "event",
  "type": "payment.failed",
  "created_at": "2024-01-20T15:30:00Z",
  "data": {
    "object": {
      "id": "tz4a98xxat96iws9zmbrgj3a",
      "object": "payment",
      "status": "failed",
      "method": "DIRECT",
      "amount": "5000000",
      "amount_paid": "0",
      "currency": "USD",
      "detected_token": "USDC",
      "detected_token_address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "detected_chain": "eip155:1",
      "token_amount": "5000000",
      "token_amount_decimal": "5",
      "on_chain_id": "0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b",
      "deposit_address": "0x5fbdb2315678afecb367f032d93f642f64180aa3",
      "deploy_tx_hash": null,
      "payer_addresses": ["0x742d35Cc6634C0532925a3b844Bc9e7595f8fE21"],
      "failure_reason": "deposit_lost_to_reorg",
      "failure_message": "The customer's deposit was confirmed but later lost to a chain reorganization.",
      "transactions": [],
      "non_funding_transactions_count": 0,
      "created_at": "2024-01-20T15:00:00Z",
      "updated_at": "2024-01-20T15:30:00Z"
    }
  }
}

{
  "id": "evt_1111aaaa2222bbbb",
  "object": "event",
  "type": "subscription_checkout.completed",
  "created_at": "2026-04-19T12:02:18Z",
  "data": {
    "object": {
      "object": "subscription_checkout",
      "id": "schk_1234567890abcdef",
      "status": "completed",
      "onchain_id": "0x9f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a",
      "business_name": "Acme Inc",
      "subscriber": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE21",
      "external_customer_id": "cus_42",
      "token_symbol": "USDC",
      "charge_amount": "9990000",
      "recommended_cap": "120000000",
      "period_duration": 2592000,
      "supported_chains": ["eip155:1", "eip155:137"],
      "completed_at": "2026-04-19T12:02:18Z",
      "created_at": "2026-04-19T12:00:00Z",
      "metadata": { "external_plan_ref": "pro_monthly" }
    },
    "subscription": {
      "object": "subscription",
      "id": "0x9f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a",
      "subscriber": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE21",
      "asset": "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "token_symbol": "USDC",
      "token_decimals": 6,
      "chain": "eip155:1",
      "cap_amount": "120000000",
      "charge_amount": "9990000",
      "period_duration": 2592000,
      "last_charged_at": "2026-04-19T12:02:18Z",
      "next_charge_at": "2026-05-19T12:02:18Z",
      "charge_nonce": 1,
      "status": "active",
      "paused": false,
      "flagged": false,
      "created_at": "2026-04-19T12:02:18Z"
    },
    "first_charge": {
      "object": "subscription_charge",
      "id": "subc_4567890abcdef123",
      "subscription_id": "0x9f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a",
      "subscriber": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE21",
      "amount": "9990000",
      "fee": "0",
      "tx_hash": "0xabc...",
      "block_number": "12345678",
      "chain": "eip155:1",
      "charge_nonce": 0,
      "charged_at": "2026-04-19T12:02:18Z"
    }
  }
}

{
  "id": "evt_3333cccc4444dddd",
  "object": "event",
  "type": "subscription.charge_succeeded",
  "created_at": "2026-05-19T12:02:18Z",
  "data": {
    "object": {
      "object": "subscription",
      "id": "0x9f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a",
      "subscriber": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE21",
      "asset": "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "token_symbol": "USDC",
      "token_decimals": 6,
      "chain": "eip155:1",
      "cap_amount": "120000000",
      "charge_amount": "9990000",
      "period_duration": 2592000,
      "last_charged_at": "2026-05-19T12:02:18Z",
      "next_charge_at": "2026-06-19T12:02:18Z",
      "charge_nonce": 2,
      "status": "active",
      "paused": false,
      "flagged": false,
      "created_at": "2026-04-19T12:02:18Z",
      "amount": "9990000",
      "fee": "0",
      "subscription_charge_id": "subc_6789abcdef012345",
      "tx_hash": "0xdef...",
      "block_number": "12346789",
      "charged_at": "2026-05-19T12:02:18Z"
    }
  }
}

{
  "id": "evt_5555eeee6666ffff",
  "object": "event",
  "type": "subscription.charge_failed",
  "created_at": "2026-06-19T12:00:00Z",
  "data": {
    "object": {
      "object": "subscription",
      "id": "0x9f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a",
      "subscriber": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE21",
      "asset": "eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "token_symbol": "USDC",
      "token_decimals": 6,
      "chain": "eip155:1",
      "cap_amount": "120000000",
      "charge_amount": "9990000",
      "period_duration": 2592000,
      "last_charged_at": "2026-05-19T12:02:18Z",
      "next_charge_at": "2026-06-19T12:02:18Z",
      "charge_nonce": 3,
      "status": "active",
      "paused": true,
      "flagged": false,
      "created_at": "2026-04-19T12:02:18Z",
      "amount": "9990000",
      "subscription_charge_id": "subc_7890abcdef123456",
      "tx_hash": "0xabc...",
      "block_number": "12350000",
      "charged_at": "2026-06-19T12:00:00Z",
      "failure_reason": "InsufficientBalance"
    }
  }
}

import crypto from 'crypto';
 
function verifyWebhookSignature(payload, signature, secret) {
  if (!signature) return false;
 
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');
 
  const sigBuffer = Buffer.from(signature);
  const expectedBuffer = Buffer.from(expectedSignature);
 
  if (sigBuffer.length !== expectedBuffer.length) return false;
 
  return crypto.timingSafeEqual(sigBuffer, expectedBuffer);
}
 
// In your webhook handler
// Use express.raw() for webhook routes to access the raw request body
app.post('/webhooks/payments', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-signature'];
  const payload = req.body; // Buffer of raw bytes, before JSON parsing
 
  if (!verifyWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
 
  // Process the event
  const event = JSON.parse(req.body);
  console.log('Received event:', event.type);
 
  res.status(200).send('OK');
});

function verifyWithRotation(payload, req, currentSecret) {
  const primary = req.headers['x-signature'];
  const previous = req.headers['x-signature-previous'];
 
  if (verifyWebhookSignature(payload, primary, currentSecret)) return true;
  // Present only during a rotation window; absent the rest of the time.
  if (previous && verifyWebhookSignature(payload, previous, currentSecret)) {
    return true;
  }
  return false;
}

app.post('/webhooks/payments', express.raw({ type: 'application/json' }), async (req, res) => {
  const signature = req.headers['x-signature'];
 
  // Verify signature
  if (!verifyWebhookSignature(req.body, signature, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
 
  const event = JSON.parse(req.body);
 
  // Handle the event
  switch (event.type) {
    case 'payment.deposit_confirmed': {
      const depositPayment = event.data.object;
      console.log('Deposit confirmed, deploy queued:', depositPayment.id);
      // Optional: show "payment received, processing" UI to customer
      break;
    }
 
    case 'payment.settled': {
      const settledPayment = event.data.object;
      console.log('Payment settled:', settledPayment.id);
      // The payment object does not echo your checkout metadata; correlate by the payment id you persisted.
      await fulfillOrder(settledPayment.id);
      break;
    }
 
    case 'payment.escrow_confirmed': {
      const escrowPayment = event.data.object;
      console.log('Funds in escrow:', escrowPayment.id);
      console.log('on_chain_id for capture/refund:', escrowPayment.on_chain_id);
      await captureOrRefund(escrowPayment.id, escrowPayment.on_chain_id);
      break;
    }
 
    case 'payment.expired': {
      const expiredPayment = event.data.object;
      console.log('Payment expired:', expiredPayment.id);
      await releaseHeldInventory(expiredPayment.id);
      break;
    }
 
    case 'payment.cancelled': {
      const cancelledPayment = event.data.object;
      console.log('Payment cancelled:', cancelledPayment.id);
      await releaseHeldInventory(cancelledPayment.id);
      break;
    }
 
    case 'payment.failed': {
      const failedPayment = event.data.object;
      console.log('Payment failed:', failedPayment.id, failedPayment.failure_reason);
      await notifyCustomer(failedPayment.id, failedPayment.failure_message);
      break;
    }
 
    case 'payment.refunded': {
      const refundedPayment = event.data.object;
      console.log('Payment refunded:', refundedPayment.id);
      await updateOrderStatus(refundedPayment.id, 'refunded');
      break;
    }
 
    case 'payment.flagged': {
      // Payer is OFAC-restricted. Funds stay held in the deposit address; they cannot be captured or refunded.
      const flaggedPayment = event.data.object;
      console.log('Payment flagged, halted:', flaggedPayment.id);
      await flagForReview(flaggedPayment.id);
      break;
    }
 
    case 'payment.screening_pending': {
      // Screening provider was unavailable; the payment is held and auto re-screened.
      const pendingPayment = event.data.object;
      console.log('Payment held for screening:', pendingPayment.id);
      break;
    }
 
    case 'subscription_checkout.completed': {
      // First successful subscribe, atomic with the first charge.
      // Payload bundles the intent, the subscription, and the first charge.
      const { object: intent, subscription, first_charge } = event.data;
      console.log('Subscription started:', subscription.id);
      await grantAccess(intent.external_customer_id);
      await recordCharge(first_charge);
      break;
    }
 
    case 'subscription_checkout.cancelled':
    case 'subscription_checkout.expired': {
      const intent = event.data.object;
      console.log(`${event.type}:`, intent.id);
      await releaseHeldInventory(intent.metadata?.order_id);
      break;
    }
 
    case 'subscription.created': {
      // Fires alongside subscription_checkout.completed for the same on-chain event.
      // Most merchants act on the checkout webhook instead. Handle this if you
      // care about subscriptions created via the indexer-only path.
      const subscription = event.data.object;
      console.log('Subscription created:', subscription.id);
      break;
    }
 
    case 'subscription.charge_succeeded': {
      // data.object is the subscription enriched with charge fields (amount, fee, tx_hash, ...).
      const charge = event.data.object;
      await recordCharge(charge);
      break;
    }
 
    case 'subscription.charge_failed': {
      // `failure_reason` is a typed contract error name; `id` is the subscription id.
      const charge = event.data.object;
      await handleFailedCharge(charge.id, charge.failure_reason);
      break;
    }
 
    case 'subscription.cap_updated': {
      // Subscriber raised/lowered the cap on the hosted page.
      const sub = event.data.object;
      console.log('Cap updated:', sub.id, sub.cap_amount);
      break;
    }
 
    case 'subscription.cancelled': {
      const cancelledSub = event.data.object;
      await revokeAccess(cancelledSub.id);
      break;
    }
 
    default:
      console.log(`Unhandled event type: ${event.type}`);
  }
 
  res.status(200).send('OK');
});

ngrok http 3000