Recepción y procesamiento de webhooks

Estado documental: Contrato propuesto. La política exacta de reintentos y los endpoints de administración se documentarán en la biblioteca de endpoints.

Concepto

YUPY
    → envía un evento

Servidor del cliente
    → valida firma
    → registra event_id
    → responde rápidamente
    → procesa el evento

Endpoint del cliente

Ejemplo:

https://api.cliente.com/webhooks/yupy

Debe utilizar HTTPS, aceptar POST, conservar el cuerpo original, verificar firma, deduplicar por event_id, responder rápidamente y procesar de forma idempotente.

Ejemplo

POST /webhooks/yupy HTTP/1.1
Host: api.cliente.com
Content-Type: application/json
Yupy-Event-Id: evt_01JXYZ
Yupy-Timestamp: 1784567890
Yupy-Signature: <SIGNATURE>

{
  "event_id": "evt_01JXYZ",
  "event_type": "payment.reconciled",
  "event_version": "1.0",
  "created_at": "2026-07-20T14:40:00-05:00",
  "data": {
    "yupy_transaction_id": "ypt_01JXYZ",
    "external_transaction_id": "ORDER-10482",
    "amount": "85.50",
    "currency": "PEN",
    "state": {
      "operational": "active",
      "financial": "reconciled"
    }
  }
}

Respuesta recomendada

HTTP/1.1 200 OK
Content-Type: application/json

{
  "received": true
}

Procesamiento asíncrono

Webhook recibido
    ↓
firma validada
    ↓
evento guardado
    ↓
respuesta 200
    ↓
procesamiento comercial

No conviene completar toda la lógica comercial antes de responder.

Duplicados de entrega

YUPY puede reenviar el mismo evento. El cliente debe reconocerlo mediante event_id.

{
  "received": true,
  "duplicate": true
}

El mismo evento no debe producir dos veces la entrega de producto, emisión de boleto, cierre de pedido, devolución ni actualización financiera.

Reintentos

Cuando el endpoint no responda o devuelva un error, YUPY puede reintentar.

mismo event_id
mismo event_type
mismo contenido financiero

La política exacta de reintentos se documentará en la biblioteca de endpoints.

Orden de eventos

El cliente no debe asumir que todos los eventos llegarán en orden perfecto.

Puede consultar el estado actual mediante:

GET /v1/payment-orders/{yupy_transaction_id}

Registro recomendado

event_id
event_type
event_version
received_at
signature_valid
processing_status
attempt_count
payload_hash
yupy_transaction_id
external_transaction_id

Criterios de aceptación

1. El endpoint utiliza HTTPS.
2. El cliente responde rápidamente.
3. El procesamiento puede ser asíncrono.
4. event_id evita efectos duplicados.
5. Los reintentos conservan el mismo evento.
6. El cliente no asume orden perfecto.
7. Puede consultar la API para confirmar estado.
8. Los errores quedan registrados.
9. El webhook se procesa idempotentemente.
10. La política exacta de entrega permanece propuesta.