Webhooks

Los webhooks le avisan a tu servidor, en tiempo real, cuando algo ocurre: un cobro aprobado, una tarjeta guardada, una sesión que expiró. Es la forma recomendada de reaccionar a los pagos (mejor que hacer polling).

Eventos disponibles

Eventos opcionales — solo Credicard

Aplican solo si cobras con Credicard. Algunas tarjetas —el débito nacional, la Master Debit— piden una verificación del tarjetahabiente: un código de su banco (OTP) o un cargo temporal cuyo monto confirma. Credicard la vuelve a pedir cada 3 meses. Estos eventos te avisan para que le pidas al cliente un pago desde el link y la verificación se renueve.

Registrar un endpoint

POST /v1/webhooks/endpoints

Autenticación: clave secreta (Authorization: Bearer sk_…).

curl -X POST https://api.seif.pagosripei.com/v1/webhooks/endpoints \
  -H "Authorization: Bearer sk_test_tu_clave" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.mitienda.com/seif/webhooks",
    "enabledEvents": ["charge.approved", "charge.declined", "charge.failed"]
  }'

La respuesta incluye un secret (whsec_…), mostrado una sola vez. Guárdalo: con él verificas la firma de cada evento.

Autenticación saliente (opcional)

Además de la firma Seif-Signature (que va siempre), puedes pedir que Seif autentique la llamada a tu endpoint para que tu receptor la valide. Se configura con authType al crear o actualizar:

curl -X POST https://api.seif.pagosripei.com/v1/webhooks/endpoints \
  -H "Authorization: Bearer sk_test_tu_clave" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://api.mitienda.com/seif/webhooks", "authType": "bearer", "authToken": "tu-token" }'

Gestionar endpoints

GET    /v1/webhooks/endpoints          # listar
GET    /v1/webhooks/endpoints/{id}     # ver uno
PATCH  /v1/webhooks/endpoints/{id}     # actualizar (URL, eventos, estado, auth)
DELETE /v1/webhooks/endpoints/{id}     # eliminar

En PATCH, omite un campo para conservarlo; en una credencial, envía "" para borrarla. Cambiar status a disabled detiene los envíos sin borrar el endpoint (el historial de entregas se conserva).

Probar un endpoint (ping)

POST /v1/webhooks/endpoints/{id}/test

Encola un evento sintético webhook.test hacia ese endpoint (con su firma y autenticación), aunque esté inactivo o no suscrito a ese evento. Devuelve { deliveryId, eventId }; el resultado aparece en el historial de entregas. Úsalo para verificar conectividad, firma y autenticación sin esperar a una transacción real.

Formato del evento

Cada entrega es un POST con este cuerpo:

{
  "id": "evt_1a2b3c...",
  "type": "charge.approved",
  "createdAt": "2026-06-09T18:05:12.000Z",
  "env": "production",
  "data": {
    "transactionReference": "txn_2nFp9Zk",
    "sessionReference": "cs_8sKd2pQ1Aa",
    "amountMinor": 105000,
    "currency": "VES",
    "status": "approved",
    "declineReason": null,
    "errorCode": null,
    "processorReference": "000000000004663"
  }
}

Cuerpo de data según el evento:

Los eventos charge.* traen además el origen del cobro: sessionReference si vino del checkout, o seifToken si fue un cobro con tarjeta guardada.

En los eventos card.authentication_*, estimatedExpiresAt es una estimación de Seif (tres meses después de la última verificación): quien decide es Credicard, y un cobro antes de esa fecha puede pedir verificación igual. transactionReference es el cobro que Credicard rechazó pidiendo la verificación.

En session.expired, reason es expired (venció por tiempo), max_failures_reached (agotó sus intentos) o merchant_request (la expiraste tú): los mismos valores que closedReason en Sesiones de pago. maxFailures es null si la sesión no tenía límite de intentos.

Por qué falló un cobro

En charge.declined y charge.failed vienen los dos campos que explican el resultado, así no hace falta consultar la transacción aparte:

Ambos son null en charge.approved.

Y al revés: en charge.approved viene processorReference, la referencia que asigna el banco. Es la que te sirve para conciliar contra tu estado de cuenta. En un rechazo va null, porque no hubo autorización que referenciar.

Verificar la firma

Cada entrega trae el header Seif-Signature:

Seif-Signature: t=1717954512,v1=5f8e...c3

Recalcula HMAC-SHA256 sobre `${t}.${cuerpoCrudo}` con tu secret (whsec_…) y compara con v1. Verifica además que t sea reciente para rechazar reenvíos.

import crypto from 'crypto';
 
function verifySeifWebhook(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${parts.t}.${rawBody}`, 'utf8')
    .digest('hex');
  const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300; // 5 min
  return ok && fresh;
}

Entregas y reintentos

• Responde 2xx rápido (idealmente < 5 s). Cualquier otra respuesta se considera fallida.
• Seif reintenta hasta 5 veces con backoff exponencial.
• Puedes consultar el historial de entregas y reintentar manualmente:

GET    /v1/webhooks/deliveries
GET    /v1/webhooks/deliveries/{id}
POST   /v1/webhooks/deliveries/{id}/retry