{
  "id": "evt_1706745600_abc123",
  "type": "payment.succeeded",
  "created": 1706745600,
  "livemode": true,
  "api_version": "2024-12-01",
  "request": {
    "id": "req_abc123def456",
    "idempotency_key": "evt_1706745600_abc123"
  },
  "data": {
    "object": {
      "object": "payment",
      "id": "chk_123456",
      "order_id": "order_789",
      "provider_order_id": "pi_stripe_abc123",
      "organization_id": "org_456",
      "brand": {
        "id": "brand_123",
        "name": "My Store"
      },
      "payment": {
        "provider": "stripe",
        "transaction_id": "pi_stripe_abc123",
        "payment_method_token": "pm_123|cus_456",
        "status": "succeeded",
        "error_message": null,
        "error_code": null
      },
      "amount": {
        "subtotal": 4999,
        "shipping": 499,
        "tax": 440,
        "discount": 0,
        "total": 5938,
        "currency": "USD"
      },
      "customer": {
        "id": null,
        "email": "john@example.com",
        "first_name": "John",
        "last_name": "Doe",
        "phone": "+1234567890",
        "ip_address": "203.0.113.1"
      },
      "billing_address": {
        "line1": "123 Main St",
        "line2": "Apt 4B",
        "city": "New York",
        "state": "NY",
        "postal_code": "10001",
        "country": "US"
      },
      "shipping_address": {
        "line1": "123 Main St",
        "line2": "Apt 4B",
        "city": "New York",
        "state": "NY",
        "postal_code": "10001",
        "country": "US"
      },
      "line_items": [
        {
          "id": "item_001",
          "product_id": "item_001",
          "name": "Premium Widget",
          "description": "High-quality premium widget",
          "sku": "WIDGET-PRO-001",
          "quantity": 2,
          "unit_price": 2499,
          "total_price": 4998,
          "image_url": "https://example.com/widget.jpg",
          "metadata": {
            "variantId": "var_123",
            "campaignProductId": "cp_456"
          }
        }
      ],
      "upsells": [
        {
          "id": "ups_001",
          "offer_id": "offer_abc",
          "product_id": "prod_xyz",
          "name": "Extended Warranty",
          "description": "2-year extended warranty",
          "sku": "WARRANTY-2YR",
          "status": "accepted",
          "price": 999,
          "original_price": 1999,
          "image_url": "https://example.com/warranty.jpg",
          "transaction_id": "pi_upsell_123",
          "accepted_at": 1706745650,
          "metadata": {
            "offerId": "sticky_offer_123"
          }
        }
      ],
      "sales_attribution": {
        "agent_id": "agent_789",
        "agent_name": "Jane Smith",
        "agent_email": "jane@company.com",
        "organization_id": "org_456",
        "team_id": "team_sales",
        "team_name": "Inside Sales",
        "commission_rate": 0.10,
        "commission_type": "percentage",
        "source": "phone_sale",
        "campaign_code": "SUMMER2024",
        "generated_at": 1706745000
      },
      "created_at": 1706745600,
      "updated_at": 1706745600,
      "completed_at": 1706745650,
      "metadata": {
        "campaign": "summer_sale",
        "source": "landing_page"
      },
      "order_metadata": {
        "warehouse_id": "WH-001",
        "fulfillment_priority": "high"
      },
      "provider_data": {}
    },
    "previous_attributes": null
  },
  "webhook_id": "wh_1706745650_xyz789",
  "delivery_attempt": 1,
  "signature_version": "v1",
  "delivered_at": "2024-01-31T12:00:50.000Z"
}

import crypto from 'crypto';

function verifyWebhook(
  rawPayload: string,
  signatureHeader: string,
  secret: string
): boolean {
  // Generate expected signature
  const expectedSignature = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawPayload)
    .digest('hex');

  // Use timing-safe comparison to prevent timing attacks
  return crypto.timingSafeEqual(
    Buffer.from(signatureHeader),
    Buffer.from(expectedSignature)
  );
}

// Express example
import express from 'express';

const app = express();

// Important: Use raw body middleware for signature verification
app.use(express.raw({ type: 'application/json' }));

app.post('/webhooks/checkout', (req, res) => {
  const signature = req.headers['x-webhook-signature'] as string;
  const payload = req.body as Buffer;

  if (!verifyWebhook(payload.toString(), signature, process.env.WEBHOOK_SECRET!)) {
    console.error('Invalid webhook signature');
    return res.status(401).send('Invalid signature');
  }

  // Signature verified, safe to process
  const event = JSON.parse(payload.toString());
  console.log('Received event:', event.type, event.id);

  // Return 2xx immediately
  res.status(200).send('OK');

  // Process asynchronously
  processEvent(event).catch(err => {
    console.error('Error processing webhook:', err);
  });
});

async function processEvent(event: any) {
  switch (event.type) {
    case 'payment.succeeded':
      await handlePaymentSuccess(event.data.object);
      break;
    case 'order.confirmed':
      await handleOrderConfirmed(event.data.object);
      break;
    case 'upsell.accepted':
      await handleUpsellAccepted(event.data.object);
      break;
    // ... handle other event types
  }
}

# Single endpoint
WEBHOOK_URLS=https://api.example.com/webhook

# Multiple endpoints (comma-separated)
WEBHOOK_URLS=https://api.example.com/webhook,https://backup.example.com/webhook

# Per-endpoint event filtering (optional)
WEBHOOK_URL_1_EVENTS=payment.succeeded,order.confirmed
WEBHOOK_URL_2_EVENTS=*

# Per-endpoint secrets (optional)
WEBHOOK_URL_1_SECRET=whsec_endpoint1_secret
WEBHOOK_URL_2_SECRET=whsec_endpoint2_secret

import express from 'express';
import crypto from 'crypto';

const app = express();

// Use raw body middleware so we can access the original request body for signature verification
app.use(express.raw({ type: 'application/json' }));

// Track processed events to handle duplicates
const processedEvents = new Set<string>();

app.post('/webhooks/checkout', async (req, res) => {
  const signature = req.headers['x-webhook-signature'] as string;
  const payload = req.body as Buffer;
  const rawPayload = payload.toString();

  // 1. Verify webhook signature
  const secret = process.env.WEBHOOK_SECRET!;
  const expectedSignature = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawPayload)
    .digest('hex');

  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expectedSignature))) {
    console.error('Invalid webhook signature');
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // 2. Parse the event
  let event;
  try {
    event = JSON.parse(rawPayload);
  } catch (err) {
    console.error('Failed to parse webhook payload:', err);
    return res.status(400).json({ error: 'Invalid JSON' });
  }

  // 3. Check for duplicates
  if (processedEvents.has(event.id)) {
    console.log('Duplicate webhook received, already processed:', event.id);
    return res.status(200).json({ message: 'Already processed' });
  }
  processedEvents.add(event.id);

  // 4. Respond immediately with 200 OK
  res.status(200).json({ message: 'Received' });

  // 5. Process the webhook asynchronously
  handleWebhook(event).catch(err => {
    console.error('Error processing webhook:', err);
    // Could implement retry logic, Sentry reporting, etc.
  });
});

async function handleWebhook(event: any) {
  const { type, data } = event;
  const object = data.object;

  console.log('Processing webhook:', {
    id: event.id,
    type: event.type,
    orderId: object.order_id,
    amount: object.amount.total,
    currency: object.amount.currency,
  });

  try {
    switch (type) {
      case 'payment.succeeded':
        await handlePaymentSuccess(object);
        break;

      case 'payment.failed':
        await handlePaymentFailed(object);
        break;

      case 'order.confirmed':
        await handleOrderConfirmed(object);
        break;

      case 'upsell.accepted':
        await handleUpsellAccepted(object);
        break;

      case 'upsell.declined':
        await handleUpsellDeclined(object);
        break;

      case 'refund.succeeded':
        await handleRefundSucceeded(object);
        break;

      default:
        // Gracefully handle unknown event types
        console.warn('Unknown event type:', type);
    }
  } catch (error) {
    console.error('Error handling event:', error);
    throw error; // Could implement retry queue here
  }
}

async function handlePaymentSuccess(object: any) {
  const { order_id, amount, customer, line_items } = object;
  console.log('Payment succeeded:', {
    orderId: order_id,
    amount: (amount.total / 100).toFixed(2),
    currency: amount.currency,
    customer: customer.email,
  });

  // Create order in your system
  // Send confirmation email
  // Trigger fulfillment
  // etc.
}

async function handlePaymentFailed(object: any) {
  const { order_id, customer, payment } = object;
  console.log('Payment failed:', {
    orderId: order_id,
    customer: customer.email,
    error: payment.error_message,
  });

  // Send failure email
  // Log for review
}

async function handleOrderConfirmed(object: any) {
  const { order_id } = object;
  console.log('Order confirmed:', order_id);

  // Update order status
  // Process shipment
}

async function handleUpsellAccepted(object: any) {
  const { order_id, upsells } = object;
  console.log('Upsell accepted:', {
    orderId: order_id,
    upsells: upsells.length,
  });

  // Charge additional amount
  // Update order with upsell products
}

async function handleUpsellDeclined(object: any) {
  const { order_id } = object;
  console.log('Upsell declined:', order_id);

  // Log decline
  // Could use for analytics
}

async function handleRefundSucceeded(object: any) {
  const { order_id, amount } = object;
  console.log('Refund succeeded:', {
    orderId: order_id,
    refundAmount: (amount.total / 100).toFixed(2),
  });

  // Update order status to refunded
  // Send refund confirmation email
}

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Webhook server listening on port ${PORT}`);
});

# Start ngrok tunnel (exposes localhost:3000 to the internet)
ngrok http 3000

# Output will show:
# Forwarding https://12345.ngrok.io -> http://localhost:3000

# Use the ngrok URL in your webhook configuration
# https://12345.ngrok.io/webhooks/checkout

# Generate signature
SECRET="whsec_your_webhook_secret"
PAYLOAD='{"id":"evt_test_123","type":"payment.succeeded",...}'
SIGNATURE="sha256=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET" -hex | sed 's/^.* //')"

# Send test webhook
curl -X POST http://localhost:3000/webhooks/checkout \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Signature: $SIGNATURE" \
  -H "X-Webhook-Event: payment.succeeded" \
  -d "$PAYLOAD"

WEBHOOK_DEBUG=true