Webhooks para desarrolladores

Los webhooks permiten recibir notificaciones en tiempo real sobre eventos en tu cuenta de Linka. Esta guia explica como configurarlos, verificarlos y procesarlos de forma segura.

Que son los webhooks

Un webhook es una llamada HTTP enviada a tu aplicacion cuando ocurre un evento especifico. En lugar de consultar la API constantemente, puedes recibir avisos inmediatos sobre:

• Cambios de estado de pagos.
• Actualizaciones de balance.
• Confirmaciones de transacciones.
• Cambios en verificacion KYC/KYB.
• Eventos de error.

Configuracion

Paso 1: Crea un endpoint

Crea un endpoint HTTP en tu aplicacion capaz de recibir solicitudes POST:

// Ejemplo: endpoint en Express.js
app.post('/webhooks/linka', async (req, res) => {
  const event = req.body;
  const signature = req.headers['linka-signature'];
  const isValid = verifyWebhookSignature(event, signature);

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  await handleWebhookEvent(event);
  res.status(200).send('OK');
});

Paso 2: Configura el endpoint en el dashboard

1. Ve a Developer -> Webhooks en tu dashboard de Linka.
2. Haz clic en Add Webhook Endpoint.
3. Ingresa la URL del endpoint. Debe usar HTTPS.
4. Selecciona los eventos que quieres recibir:
   • payment.completed
   • payment.failed
   • wallet.balance_updated
   • transaction.status_changed
   • compliance.verification_completed
5. Guarda la configuracion.

Paso 3: Verifica la firma

Todas las solicitudes webhook incluyen una firma para validacion:

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const computed = hmac.update(JSON.stringify(payload)).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(computed)
  );
}

Estructura de eventos

Todos los eventos siguen esta estructura:

{
  "id": "evt_1234567890",
  "type": "payment.completed",
  "created": 1640995200,
  "data": {
    "object": "payment",
    "id": "pay_abc123",
    "amount": "100.00",
    "currency": "USDC",
    "status": "completed"
  }
}

Tipos de evento

Pagos

• payment.created: se inicio un pago.
• payment.completed: el pago fue completado.
• payment.failed: el pago fallo.
• payment.refunded: el pago fue reembolsado.

Wallets

• wallet.created: se creo una wallet.
• wallet.balance_updated: cambio el balance.
• wallet.address_generated: se genero una nueva direccion.

Transacciones

• transaction.status_changed: cambio el estado de una transaccion.
• transaction.confirmed: la transaccion fue confirmada on-chain.

Cumplimiento

• compliance.verification_started: inicio una verificacion KYC/KYB.
• compliance.verification_completed: la verificacion fue completada.
• compliance.verification_failed: la verificacion fallo.

Probar webhooks

Usa la herramienta de prueba del dashboard:

1. Ve a Developer -> Webhooks.
2. Abre tu endpoint.
3. Haz clic en Send Test Event.
4. Verifica que tu aplicacion reciba el evento.

Buenas practicas

• Verifica siempre la firma para confirmar que el evento viene de Linka.
• Responde 200 OK rapido y procesa tareas pesadas de forma asincrona.
• Implementa idempotencia usando el ID del evento.
• Registra eventos para depuracion y auditoria.

Siguientes pasos

• Revisa la referencia de webhooks.
• Configura el ambiente sandbox.
• Explora casos comunes en on-ramp.