Webhooks de eventos (POST)

Crowder te notifica las transiciones del lifecycle vía webhooks. Cada evento dispara una transición concreta; no hay eventos puramente informativos.

Request

POST {endpoint}/{interaction}/events

Headers:

Authorization: Bearer <api_key>
Content-Type: application/json

`interaction` viaja en la URL

El body no repite la interaction: vive solo en el path. Identificás la operación por el path; el body lleva únicamente status + los subobjetos del evento.

Eventos y transiciones

status	Transición	Trigger	Campos relevantes
purchaseReserved	valid → reserved	Crowder te pide reservar stock real. Vos devolvés expiresAt en el ack — el TTL arranca acá.	currency, partnerItems
purchasePaid	reserved → confirmed	Pago capturado en Crowder.	currency, purchase, partnerItems
purchaseExpired	reserved → expired	El TTL de la reserva venció sin pago. Crowder notifica para que el partner libere el hold de forma sincronizada (no solo por su cuenta).	status
purchaseRefunded	confirmed → confirmed (parcial) o confirmed → refunded (total)	Devolución de uno o más items. Crowder envía un array items con qué devolver. Si abarca todos los items vigentes → terminal refunded. Si es subset → la interacción queda en confirmed con partnerItems reducido.	reason, items

Secuencia happy path: purchaseReserved → purchasePaid.

Devoluciones consensuadas vs. forzadas

Crowder solo pide devolver items marcados refundable: true en el GET de estado. Los casos no consensuados (chargeback, fraud) bypasean ese flag — la plata ya se fue y el partner debe revertir el fulfillment correspondiente igual.

Si el partner es quien necesita devolver post-pago (ej: aerolínea cancela vuelo, hotel cierra), el flujo correcto sigue siendo purchaseRefunded con reason: cancelled_by_partner. Una interacción que nunca llegó a confirmed simplemente expira por TTL en reserved o queda perpetua en valid — no genera webhook.

Bodies de ejemplo

purchaseReserved

{
  "status": "purchaseReserved",
  "currency": "ARS",
  "partnerItems": [
    {
      "uuid": "HOTEL-3N-PREMIUM",
      "type": "HOTEL",
      "description": "Hotel 3 noches · Hilton Buenos Aires",
      "price": 120000.00,
      "quantity": 1
    }
  ]
}

purchasePaid

{
  "status": "purchasePaid",
  "currency": "ARS",
  "purchase": { "id": 987654, "amount": 120000.00 },
  "partnerItems": [/* ... */]
}

purchaseExpired

{
  "status": "purchaseExpired"
}

El body no lleva más campos: la interaction viaja en la URL y el evento es puramente notificacional. El partner libera el hold y responde 200 con { "status": "expired" }.

purchaseRefunded

{
  "status": "purchaseRefunded",
  "reason": "user_request",
  "items": [
    { "uuid": "TICKET-VIP" }
  ]
}

reason: user_request | cancelled_by_partner | chargeback | fraud | other.

Devoluciones parciales

items lista qué devolver. Si abarca todos los items vigentes de la compra → terminal refunded. Si es un subset → la interacción queda en confirmed con partnerItems reducido (los items devueltos salen del array).

Crowder solo pide devolver items declarados refundable: true en el GET de estado, salvo reason: chargeback | fraud que bypasean el flag.

Ack al webhook

No hay envelope acknowledged. El código HTTP carga el significado y el body lleva el status resultante del lifecycle como discriminador, más los campos que el partner aporta como output.

HTTP	Body	Significado
200	{ "status": "<lifecycle>", ... } con el lifecycle alcanzado: reserved (lleva expiresAt), confirmed, expired, refunded	Procesado correctamente.
202	{ "status": "deferred", "notes"?: "..." }	Recibido, procesamiento async.
409	{ "status": "error", "error": { "code": "invalid_transition", "message": "..." } }	El estado actual no admite el evento. No se mutó nada.
400	{ "status": "error", "error": { "code": "invalid_payload" | "unsupported_event", ... } }	Payload mal formado o evento desconocido.
401 / 403	{ "status": "error", "error": { "code": "auth_invalid", ... } }	Bearer ausente o inválido.
404	{ "status": "error", "error": { "code": "not_found", ... } }	interaction desconocida.
5xx	(libre)	Error interno. Entra a reintentos.

200 OK · ack del purchaseReserved (TTL arranca acá)

{ "status": "reserved", "expiresAt": "2026-04-28T15:48:00Z" }

200 OK · ack de purchasePaid

{ "status": "confirmed" }

200 OK · ack de purchaseExpired

{ "status": "expired" }

200 OK · ack de purchaseRefunded (parcial — quedan items vigentes)

{ "status": "confirmed" }

200 OK · ack de purchaseRefunded (total)

{ "status": "refunded" }

202 Accepted · partner difiere el procesamiento

{
  "status": "deferred",
  "notes": "Encolado en queue de fulfillment. Ref: voucher-q-4528."
}

409 Conflict · transición inválida

{
  "status": "error",
  "error": {
    "code": "invalid_transition",
    "message": "Evento purchasePaid requiere lifecycle=\"reserved\", actual=\"valid\"."
  }
}

Nota

Ante un deferred, Crowder no espera notificación posterior del partner: el siguiente GET de estado refleja la realidad cuando el partner termine de procesar.

Reintentos e idempotencia

Backoff exponencial: 1m → 5m → 30m → 2h → 12h → 24h. Después: failed en backoffice.

• 4xx salen del ciclo de reintentos (no se vuelve a intentar).
• 5xx entra al backoff exponencial.

Deduplicación obligatoria

El partner deduplica por PK (interaction, status) y re-responde el ack original ante reintentos. Nunca cumplas dos veces la misma operación.

Validación de transición

El partner valida que su lifecycle actual coincida con el “from” de la tabla. Si no encaja (ej: purchasePaid sobre valid), respondé 409 invalid_transition sin mutar nada. Crowder consulta el GET de estado antes de disparar, así que un 409 indica una divergencia que requiere resolución bilateral.