Configuración de webhooks

Aprende a configurar webhooks en tus claves de API de OrcaRail para recibir notificaciones de pago en tiempo real.

Visión general

En OrcaRail, los webhooks se configuran a nivel de clave de API. Cada clave de API puede tener su propia URL de webhook, lo que te permite:

Enviar distintos eventos a distintos endpoints
Usar webhooks separados para cada entorno (desarrollo, staging, producción)
Probar los webhooks de cada clave de API de forma independiente

Configurar webhooks

Paso 1: crea o actualiza una clave de API

Los webhooks se configuran al crear o actualizar una clave de API. Puedes definir el parámetro webhookUrl:

Crear una clave de API con URL de webhook

POST /api/v1/organizations/:organizationId/api-keys
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

Sustituye :organizationId por la organización que quieres gestionar. La encontrarás en Panel → Configuración de la organización, o llamando al endpoint que lista tus organizaciones y copiando el id de la que quieras usar. El token bearer debe pertenecer a un usuario o sesión que pueda gestionar esa misma organización.

Cuerpo de la petición:

{
  "name": "Production API Key",
  "webhookUrl": "https://api.example.com/webhooks/orcarail"
}

Respuesta:

{
  "apiKey": {
    "id": 1,
    "name": "Production API Key",
    "keyPrefix": "ak_live_",
    "status": "active",
    "webhookUrl": "https://api.example.com/webhooks/orcarail",
    "createdAt": "2024-01-01T00:00:00.000Z"
  },
  "key": "ak_live_abc123def456",
  "secret": "sk_live_xyz789uvw012"
}

Actualizar la URL de webhook de una clave de API

Puedes actualizar la URL de webhook de una clave de API existente:

PATCH /api/v1/api-keys/:id
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

Cuerpo de la petición:

{
  "webhookUrl": "https://api.example.com/webhooks/orcarail"
}

Respuesta:

{
  "id": 1,
  "name": "Production API Key",
  "keyPrefix": "ak_live_",
  "status": "active",
  "webhookUrl": "https://api.example.com/webhooks/orcarail",
  "updatedAt": "2024-01-01T12:00:00.000Z"
}

Paso 2: requisitos de la URL de webhook

Tu URL de webhook debe cumplir estos requisitos:

HTTPS: obligatorio en producción (se permite HTTP en desarrollo local)
Accesible públicamente: OrcaRail debe poder llegar a ella desde internet
Endpoint HTTP válido: debe aceptar peticiones POST
Respuesta rápida: debe devolver 200 OK en menos de 10 segundos (el tiempo de espera es de 10 segundos)

Paso 3: quita la URL de webhook

Para dejar de recibir webhooks de una clave de API, pon webhookUrl a null:

PATCH /api/v1/api-keys/:id
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

Cuerpo de la petición:

{
  "webhookUrl": null
}

Ejemplos de código

JavaScript/TypeScript

// Create API key with webhook URL
const response = await fetch(
  'https://api.orcarail.com/api/v1/organizations/org_123/api-keys',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${jwtToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      name: 'Production API Key',
      webhookUrl: 'https://api.example.com/webhooks/orcarail',
    }),
  }
)

const { apiKey, key, secret } = await response.json()
console.log('API Key created:', key)
console.log('Webhook URL:', apiKey.webhookUrl)

// Update webhook URL
const updateResponse = await fetch(
  `https://api.orcarail.com/api/v1/api-keys/${apiKey.id}`,
  {
    method: 'PATCH',
    headers: {
      Authorization: `Bearer ${jwtToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      webhookUrl: 'https://api.example.com/webhooks/orcarail-v2',
    }),
  }
)

Python

import requests

# Create API key with webhook URL
response = requests.post(
    'https://api.orcarail.com/api/v1/organizations/org_123/api-keys',
    headers={
        'Authorization': f'Bearer {jwt_token}',
        'Content-Type': 'application/json',
    },
    json={
        'name': 'Production API Key',
        'webhookUrl': 'https://api.example.com/webhooks/orcarail',
    },
)

data = response.json()
api_key = data['apiKey']
print(f"API Key created: {data['key']}")
print(f"Webhook URL: {api_key['webhookUrl']}")

# Update webhook URL
update_response = requests.patch(
    f"https://api.orcarail.com/api/v1/api-keys/{api_key['id']}",
    headers={
        'Authorization': f'Bearer {jwt_token}',
        'Content-Type': 'application/json',
    },
    json={
        'webhookUrl': 'https://api.example.com/webhooks/orcarail-v2',
    },
)

cURL

# Create API key with webhook URL
curl -X POST https://api.orcarail.com/api/v1/organizations/org_123/api-keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API Key",
    "webhookUrl": "https://api.example.com/webhooks/orcarail"
  }'

# Update webhook URL
curl -X PATCH https://api.orcarail.com/api/v1/api-keys/1 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://api.example.com/webhooks/orcarail-v2"
  }'

Probar la configuración de tu webhook

Con el endpoint de webhook de prueba

OrcaRail ofrece endpoints para probar la configuración de tu webhook:

Enviar un webhook de prueba

Envía un evento de prueba payment_intent.completed a la URL de webhook configurada:

POST /api/v1/webhooks/test/:apiKeyId
Authorization: Bearer YOUR_JWT_TOKEN

Respuesta:

{
  "success": true
}

Ejemplo:

const response = await fetch(
  'https://api.orcarail.com/api/v1/webhooks/test/1',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${jwtToken}`,
    },
  }
)

const result = await response.json()
console.log('Test webhook sent:', result.success)

Enviar un webhook personalizado

Envía un payload personalizado para probar tu gestor de webhooks:

POST /api/v1/webhooks/test/:apiKeyId/custom
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

Cuerpo de la petición:

{
  "payload": {
    "type": "payment_intent.completed",
    "data": {
      "object": {
        "id": "550e8400-e29b-41d4-a716-446655440001",
        "amount": "100.00",
        "currency": "usd",
        "status": "succeeded"
      }
    }
  }
}

Respuesta:

{
  "success": true
}

Ver los registros de webhooks

Comprueba el estado de entrega de tus webhooks:

GET /api/v1/webhooks/logs?limit=50&offset=0
Authorization: Bearer YOUR_JWT_TOKEN

Parámetros de consulta:

Parámetro	Tipo	Por defecto	Descripción
`limit`	number	50	Número de registros que se devuelven
`offset`	number	0	Número de registros que se omiten

Respuesta:

{
  "logs": [
    {
      "id": 1,
      "apiKeyId": 1,
      "event": "payment_intent.completed",
      "url": "https://api.example.com/webhooks/orcarail",
      "statusCode": 200,
      "success": true,
      "attemptNumber": 1,
      "createdAt": "2024-01-01T00:00:00.000Z"
    }
  ],
  "total": 1
}

Ejemplo:

const response = await fetch(
  'https://api.orcarail.com/api/v1/webhooks/logs?limit=10&offset=0',
  {
    headers: {
      Authorization: `Bearer ${jwtToken}`,
    },
  }
)

const { logs, total } = await response.json()
console.log(`Found ${total} webhook logs`)
logs.forEach((log) => {
  console.log(`${log.event}: ${log.success ? 'Success' : 'Failed'}`)
})

Buenas prácticas

1. Usa webhooks distintos para cada entorno

Crea claves de API separadas con distintas URLs de webhook para cada entorno:

// Development
{
  name: "Development API Key",
  webhookUrl: "https://dev.example.com/webhooks/orcarail"
}

// Staging
{
  name: "Staging API Key",
  webhookUrl: "https://staging.example.com/webhooks/orcarail"
}

// Production
{
  name: "Production API Key",
  webhookUrl: "https://api.example.com/webhooks/orcarail"
}

2. Prueba antes de producción

Prueba siempre tu endpoint de webhook antes de usarlo en producción:

Usa el endpoint de webhook de prueba para comprobar que tu gestor funciona
Revisa los registros de webhooks para asegurarte de que la entrega es correcta
Comprueba que la validación de firmas funciona bien

3. Supervisa la entrega de webhooks

Revisa periódicamente los registros de webhooks para asegurarte de que:

Los webhooks se entregan correctamente
Los tiempos de respuesta son aceptables
No se producen errores

4. Gestiona los fallos de webhook

OrcaRail reintenta automáticamente los webhooks fallidos:

Intentos máximos: 3 intentos (1 inicial + 2 reintentos)
Estrategia de espera: backoff exponencial que empieza en 2 segundos
Tiempo de espera: 10 segundos por petición

Asegúrate de que tu endpoint de webhook gestiona bien los reintentos (haz que los gestores sean idempotentes).

5. Usa ngrok para el desarrollo local

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

# Install ngrok
npm install -g ngrok

# Expose local server
ngrok http 3000

Después configura tu URL de webhook con la URL de ngrok:

https://abc123.ngrok.io/webhooks/orcarail

Solución de problemas

El webhook no recibe eventos

Comprueba el estado de la clave de API: asegúrate de que tu clave de API está activa
Verifica la URL del webhook: confirma que la URL está bien configurada
Revisa los registros de webhooks: busca errores de entrega en los registros
Prueba el webhook: usa el endpoint de prueba para verificar la conectividad

El webhook devuelve 404

Comprueba que tu endpoint de webhook existe y acepta peticiones POST
Comprueba que la ruta de la URL es correcta
Asegúrate de que tu servidor está en marcha y es accesible

El webhook devuelve 500

Revisa los registros de tu servidor en busca de errores
Comprueba que tu gestor de webhooks no lanza excepciones
Asegúrate de devolver 200 OK aunque falle el procesamiento

Falla la verificación de la firma

Comprueba que usas el secreto correcto (el de la clave de API)
Asegúrate de calcular la firma correctamente
Comprueba que usas el cuerpo de la petición en bruto (no el JSON ya analizado)

Próximos pasos

Visión general de webhooks: aprende lo básico de los webhooks
Eventos de webhook: conoce los eventos disponibles
Firmas de webhooks: protege tus webhooks
Guía de claves de API: gestiona tus claves de API

Visión general​

Configurar webhooks​

Paso 1: crea o actualiza una clave de API​

Crear una clave de API con URL de webhook​

Actualizar la URL de webhook de una clave de API​

Paso 2: requisitos de la URL de webhook​

Paso 3: quita la URL de webhook​

Ejemplos de código​

JavaScript/TypeScript​

Python​

cURL​

Probar la configuración de tu webhook​

Con el endpoint de webhook de prueba​

Enviar un webhook de prueba​

Enviar un webhook personalizado​

Ver los registros de webhooks​

Buenas prácticas​

1. Usa webhooks distintos para cada entorno​

2. Prueba antes de producción​

3. Supervisa la entrega de webhooks​

4. Gestiona los fallos de webhook​

5. Usa ngrok para el desarrollo local​

Solución de problemas​

El webhook no recibe eventos​

El webhook devuelve 404​

El webhook devuelve 500​

Falla la verificación de la firma​

Próximos pasos​

Visión general

Configurar webhooks

Paso 1: crea o actualiza una clave de API

Crear una clave de API con URL de webhook

Actualizar la URL de webhook de una clave de API

Paso 2: requisitos de la URL de webhook

Paso 3: quita la URL de webhook

Ejemplos de código

JavaScript/TypeScript

Python

cURL

Probar la configuración de tu webhook

Con el endpoint de webhook de prueba

Enviar un webhook de prueba

Enviar un webhook personalizado

Ver los registros de webhooks

Buenas prácticas

1. Usa webhooks distintos para cada entorno

2. Prueba antes de producción

3. Supervisa la entrega de webhooks

4. Gestiona los fallos de webhook

5. Usa ngrok para el desarrollo local

Solución de problemas

El webhook no recibe eventos

El webhook devuelve 404

El webhook devuelve 500

Falla la verificación de la firma

Próximos pasos