Saltar al contenido principal

Eventos de webhook

OrcaRail envía eventos de webhook para avisarte de cambios en los Payment Intents y otros recursos.

Estructura del evento​

Todos los eventos de webhook siguen esta estructura:

{
  "type": "payment_intent.completed",
  "livemode": true,
  "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"
    }
  }
}

livemode es false en los eventos de una organización sandbox (testnets, sin fondos reales). Nunca completes pedidos reales a partir de eventos con livemode: false. Los pagos sandbox simulados también llevan latest_transaction.simulated: true.

Eventos de Payment Intent​

payment_intent.completed​

Se envía cuando un Payment Intent se ha completado y el pago se ha procesado. (En ejemplos antiguos puede aparecer payment_intent.succeeded; trátalo como un alias de payment_intent.completed.)

Tipo de evento: 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"
    }
  }
}

Cuándo usarlo:

  • Completar pedidos
  • Enviar emails de confirmación
  • Actualizar tu base de datos
  • Lanzar flujos de entrega

Ejemplo de gestor:

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​

Se envía cuando un Payment Intent se está procesando en la blockchain.

Tipo de evento: 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"
    }
  }
}

Cuándo usarlo:

  • Mostrar a los clientes el estado de procesamiento
  • Actualizar la interfaz para indicar que el pago está en curso
  • Registrar eventos de procesamiento

Ejemplo de gestor:

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​

Se envía cuando se cancela un Payment Intent.

Tipo de evento: 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"
    }
  }
}

Cuándo usarlo:

  • Liberar el inventario reservado
  • Cancelar pedidos pendientes
  • Avisar a los clientes
  • Limpiar recursos

Ejemplo de gestor:

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​

Se envía cuando un Payment Intent necesita que se le asocie un método de pago.

Tipo de evento: 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"
    }
  }
}

Cuándo usarlo:

  • Seguir sesiones de pago abandonadas
  • Enviar emails de recordatorio
  • Actualizar las analíticas

Ejemplo de gestor:

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
}

Gestionar eventos​

Enrutador de eventos​

Crea un enrutador para gestionar los distintos tipos de evento:

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 })
})

Idempotencia​

Asegúrate de que tus gestores sean idempotentes:

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())
}

Probar eventos​

Con el endpoint de prueba​

Puedes probar tu endpoint de webhook enviando eventos de prueba:

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"
        }
      }
    }
  }'

Próximos pasos​