Skip to main content

Webhook Events

OrcaRail sends webhook events to notify you about changes to Payment Intents and other resources.

Event Structure​

All webhook events follow this structure:

{
  "type": "payment_intent.completed",
  "data": {
    "object": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "amount": "100.00",
      "currency": "usd",
      "status": "completed",
      "paymentMethodTypes": ["crypto"],
      "metadata": {
        "order_id": "12345"
      },
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z"
    }
  }
}

Payment Intent Events​

payment_intent.completed​

Sent when a Payment Intent has succeeded and payment has been processed. (You may also see payment_intent.succeeded in older examples; treat it as an alias for payment_intent.completed.)

Event Type: payment_intent.completed

Payload:

{
  "type": "payment_intent.completed",
  "data": {
    "object": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "amount": "100.00",
      "currency": "usd",
      "status": "completed",
      "paymentMethodTypes": ["crypto"],
      "metadata": {
        "order_id": "12345"
      },
      "latestTransaction": {
        "id": "txn_1234567890",
        "status": "completed",
        "hash": "0x1234567890abcdef...",
        "amount": "100.00",
        "currency": "usd"
      },
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z"
    }
  }
}

When to Use:

  • Fulfill orders
  • Send confirmation emails
  • Update your database
  • Trigger fulfillment workflows

Example Handler:

async function handlePaymentIntentSucceeded(event) {
  const paymentIntent = event.data.object
  const orderId = paymentIntent.metadata.order_id

  // Fulfill the order
  await fulfillOrder(orderId)

  // Send confirmation email
  await sendConfirmationEmail(paymentIntent)

  // Update database
  await updateOrderStatus(orderId, 'paid')
}

payment_intent.processing​

Sent when a Payment Intent is being processed on the blockchain.

Event Type: payment_intent.processing

Payload:

{
  "type": "payment_intent.processing",
  "data": {
    "object": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "amount": "100.00",
      "currency": "usd",
      "status": "processing",
      "paymentMethodTypes": ["crypto"],
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z"
    }
  }
}

When to Use:

  • Show processing status to customers
  • Update UI to indicate payment is in progress
  • Log processing events

Example Handler:

async function handlePaymentIntentProcessing(event) {
  const paymentIntent = event.data.object
  const orderId = paymentIntent.metadata.order_id

  // Update order status to processing
  await updateOrderStatus(orderId, 'processing')

  // Notify customer
  await notifyCustomer(orderId, 'Your payment is being processed')
}

payment_intent.canceled​

Sent when a Payment Intent is canceled.

Event Type: payment_intent.canceled

Payload:

{
  "type": "payment_intent.canceled",
  "data": {
    "object": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "amount": "100.00",
      "currency": "usd",
      "status": "canceled",
      "paymentMethodTypes": ["crypto"],
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z"
    }
  }
}

When to Use:

  • Release reserved inventory
  • Cancel pending orders
  • Notify customers
  • Clean up resources

Example Handler:

async function handlePaymentIntentCanceled(event) {
  const paymentIntent = event.data.object
  const orderId = paymentIntent.metadata.order_id

  // Release inventory
  await releaseInventory(orderId)

  // Cancel order
  await cancelOrder(orderId)

  // Notify customer
  await notifyCustomer(orderId, 'Your payment was canceled')
}

payment_intent.requires_payment_method​

Sent when a Payment Intent requires a payment method to be attached.

Event Type: payment_intent.requires_payment_method

Payload:

{
  "type": "payment_intent.requires_payment_method",
  "data": {
    "object": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "amount": "100.00",
      "currency": "usd",
      "status": "requires_payment_method",
      "paymentMethodTypes": ["crypto"],
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z"
    }
  }
}

When to Use:

  • Track abandoned pay sessions
  • Send reminder emails
  • Update analytics

Example Handler:

async function handlePaymentIntentRequiresPaymentMethod(event) {
  const paymentIntent = event.data.object

  // Track abandoned pay
  await trackAbandonedPay(paymentIntent.id)

  // Send reminder email after delay
  setTimeout(
    () => {
      sendReminderEmail(paymentIntent)
    },
    24 * 60 * 60 * 1000
  ) // 24 hours
}

Handling Events​

Event Router​

Create a router to handle different event types:

const eventHandlers = {
  'payment_intent.completed': handlePaymentIntentSucceeded,
  'payment_intent.succeeded': handlePaymentIntentSucceeded, // alias
  'payment_intent.processing': handlePaymentIntentProcessing,
  'payment_intent.canceled': handlePaymentIntentCanceled,
  'payment_intent.requires_payment_method':
    handlePaymentIntentRequiresPaymentMethod,
}

app.post('/webhooks/orcarail', express.json(), async (req, res) => {
  const event = req.body

  // Verify signature
  verifyWebhookSignature(req)

  // Get handler for event type
  const handler = eventHandlers[event.type]

  if (handler) {
    try {
      await handler(event)
    } catch (error) {
      console.error(`Error handling ${event.type}:`, error)
      // Still return 200 to prevent retries if you handle errors internally
    }
  } else {
    console.log(`Unhandled event type: ${event.type}`)
  }

  res.status(200).json({ received: true })
})

Idempotency​

Ensure your handlers are idempotent:

const processedEvents = new Map()

async function handlePaymentIntentSucceeded(event) {
  const eventId = `${event.type}_${event.data.object.id}`

  // Check if already processed
  if (processedEvents.has(eventId)) {
    console.log(`Event ${eventId} already processed`)
    return
  }

  // Process event
  await fulfillOrder(event.data.object.metadata.order_id)

  // Mark as processed (with timestamp for cleanup)
  processedEvents.set(eventId, Date.now())
}

Testing Events​

Using the Test Endpoint​

You can test your webhook endpoint by sending test events:

curl -X POST https://your-webhook-url.com/webhooks/orcarail \
  -H "Content-Type: application/json" \
  -H "x-webhook-signature: test-signature" \
  -d '{
    "type": "payment_intent.completed",
    "data": {
      "object": {
        "id": "550e8400-e29b-41d4-a716-446655440001",
        "amount": "100.00",
        "currency": "usd",
        "status": "completed",
        "paymentMethodTypes": ["crypto"],
        "metadata": {
          "order_id": "test_order_123"
        }
      }
    }
  }'

Next Steps​