Saltar al contenido principal

Visión general de webhooks

Los webhooks te permiten recibir notificaciones en tiempo real sobre lo que ocurre en tu cuenta de OrcaRail, por ejemplo cuando un pago se completa o falla.

¿Qué son los webhooks?​

Los webhooks son callbacks HTTP que OrcaRail envía a tu servidor cuando ocurren determinados eventos. En lugar de consultar la API para ver si hay cambios, los webhooks envían los datos del evento a tu aplicación en tiempo real.

Cómo funcionan los webhooks​

  1. Ocurre un evento en OrcaRail (por ejemplo, un pago se completa)
  2. OrcaRail envía una petición HTTP POST a tu endpoint de webhook
  3. Tu servidor responde con 200 OK para confirmar la recepción
  4. Tu aplicación procesa el evento

Configurar webhooks​

1. Crea un endpoint de webhook​

Crea en tu aplicación un endpoint HTTP que pueda recibir peticiones POST:

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

  // Process the event
  handleWebhookEvent(event)

  // Always return 200 OK immediately
  res.status(200).json({ received: true })
})

2. Configura la URL de tu webhook​

Configura la URL de tu endpoint de webhook al crear o actualizar una clave de API. La URL del webhook debe ser:

  • Accesible públicamente: OrcaRail tiene que poder llegar a ella desde internet
  • HTTPS: por seguridad (obligatorio en producción)
  • Rápida: responde con 200 OK en menos de 10 segundos (el tiempo de espera es de 10 segundos)

Consulta Configuración de webhooks para ver instrucciones detalladas.

3. Verifica las firmas de los webhooks​

Verifica siempre las firmas de los webhooks para asegurarte de que las peticiones vienen realmente de OrcaRail. Consulta Firmas de webhooks para más detalles.

Eventos de webhook​

OrcaRail envía eventos de webhook para distintas actividades relacionadas con los pagos:

EventoDescripción
payment_intent.completedUn Payment Intent se ha completado y el pago se ha procesado
payment_intent.processingUn Payment Intent se está procesando en la blockchain
payment_intent.canceledUn Payment Intent se ha cancelado
payment_intent.requires_payment_methodUn Payment Intent necesita un método de pago

Consulta Eventos de webhook para ver información detallada de cada tipo de evento.

Payload del webhook​

Todos los eventos de webhook siguen esta estructura:

{
  "type": "payment_intent.completed",
  "data": {
    "object": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "amount": "100.00",
      "currency": "usd",
      "status": "completed",
      "metadata": {
        "order_id": "12345"
      }
    }
  }
}

Gestionar webhooks​

Idempotencia​

Un mismo evento puede enviarse varias veces. Haz siempre que tus gestores de webhooks sean idempotentes:

const processedEvents = new Set()

app.post('/webhooks/orcarail', express.json(), async (req, res) => {
  const event = req.body
  const eventId = `${event.type}_${event.data.object.id}`

  // Check if we've already processed this event
  if (processedEvents.has(eventId)) {
    return res.status(200).json({ received: true })
  }

  // Process the event
  await handleWebhookEvent(event)

  // Mark as processed
  processedEvents.add(eventId)

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

Responde rápido​

Responde siempre con 200 OK en menos de 10 segundos (el tiempo de espera del webhook) y procesa el evento de forma asíncrona:

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

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

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

Gestión de errores​

Si tu endpoint devuelve un código distinto de 200, OrcaRail reintentará el webhook. Implementa una gestión de errores adecuada:

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

    // Verify signature
    verifyWebhookSignature(req)

    // Process event
    await handleWebhookEvent(event)

    res.status(200).json({ received: true })
  } catch (error) {
    console.error('Webhook error:', error)

    // Return 500 to trigger retry, or 200 if you don't want retries
    res.status(500).json({ error: 'Internal server error' })
  }
})

Probar webhooks​

Con ngrok​

Para el desarrollo local, usa ngrok para exponer tu servidor local:

ngrok http 3000

Después configura la URL de tu webhook como https://your-ngrok-url.ngrok.io/webhooks/orcarail.

Con cURL​

Puedes probar tu endpoint de webhook manualmente:

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

Próximos pasos​