Documentación
Eventos y webhooks
Cada cambio de estado de un pago produce un evento que llega por webhook al servidor del dueño y se puede leer 30 días con GET /v1/events; la lista de tipos es abierta, así que ignora los que no conozcas.
Cómo se entregan
- Los webhooks son para el servidor del dueño. El agente no los recibe: consulta el pago con
GET /v1/spends/{id}. - Cada evento lleva
id,sequence(entero creciente por entorno),livemodey la versión de la API. Se entrega al menos una vez: deduplica poridy descarta los desequencemenor a uno ya aplicado. - La firma va en la cabecera
Nouron-Signaturecon el formatot=<segundos>,v1=<hex>: un HMAC-SHA256 del texto<t>.<cuerpo crudo>con el secretowhsec_…del destino, con tolerancia de 300 segundos. Durante una rotación llegan dos firmasv1; basta con que una coincida. - Responde 2xx apenas leas la entrega y procesa después. Si no, se reintenta 8 veces en unas 24 horas.
GET /v1/eventssirve de respaldo: guarda los últimos 30 días.
{ "id": "evt_<32 hex>", "object": "event", "type": "spend.settled", "api_version": "2026-10-01", "created": "2026-10-09T14:03:24Z", "livemode": false, "sequence": 42, "agent_id": "agt_<32 hex>", "data": { "object": { "id": "spd_<32 hex>", "object": "spend", "status": "settled" } }}Los tipos de evento
Hoy hay 32 tipos de evento: 19 de la primera fase, 11 de auditoría y 2 reservados.
Los tipos spend.created y approval.expired de la versión anterior ya no existen.
Pagos
spend.pending_approval
El pago espera la aprobación del dueño (T2, T10).
objeto: spend · lo ve: agente y dueño · fase: primera fase
spend.approved
Pasaron las reglas; cupo reservado, aún no enviado (T3, T4).
objeto: spend · lo ve: agente y dueño · fase: primera fase
spend.declined
No se pagó: una regla, el dueño o un cambio entre pasos (T1, T5, T6, T11).
objeto: spend · lo ve: agente y dueño · fase: primera fase
spend.processing
Se envió al riel; sin resultado todavía (T9).
objeto: spend · lo ve: agente y dueño · fase: primera fase
spend.settled
Pago confirmado; el objeto trae settlement.receipt_id (T14).
objeto: spend · lo ve: agente y dueño · fase: primera fase
spend.failed
Se aprobó y el riel rechazó; no se movió dinero (T15).
objeto: spend · lo ve: agente y dueño · fase: primera fase
spend.expired
La aprobación venció sin respuesta (T7, T12).
objeto: spend · lo ve: agente y dueño · fase: primera fase
spend.cancelled
El agente canceló antes del envío (T8, T13).
objeto: spend · lo ve: agente y dueño · fase: primera fase
spend.refunded
Devolución posterior a settled (T17).
objeto: spend · lo ve: agente y dueño · fase: reservado
spend.disputed
Reclamo abierto sobre un pago liquidado (T18).
objeto: spend · lo ve: agente y dueño · fase: reservado
Aprobaciones
approval.requested
Se creó una aprobación pendiente para el dueño.
objeto: approval · lo ve: solo el dueño · fase: primera fase
approval.decided
El dueño aprobó o rechazó; trae canal y referencia del aprobador.
objeto: approval · lo ve: solo el dueño · fase: primera fase
Fondeo
funding.awaiting_deposit
Esperando un depósito en la bolsa de práctica.
objeto: funding · lo ve: solo el dueño · fase: primera fase
funding.deposit_received
Llegó un depósito.
objeto: funding · lo ve: solo el dueño · fase: primera fase
funding.converted
Un depósito se convirtió a dólares digitales de práctica.
objeto: funding · lo ve: solo el dueño · fase: primera fase
funding.failed
Un depósito no se pudo completar.
objeto: funding · lo ve: solo el dueño · fase: primera fase
Billetera
wallet.low_balance
El saldo bajó del umbral de aviso.
objeto: wallet · lo ve: solo el dueño · fase: primera fase
Reglas
policy.updated
Se público una versión nueva de las reglas; trae version y hash.
objeto: policy · lo ve: agente y dueño · fase: primera fase
policy.change_requested
Se pidió un cambio que AFLOJA reglas; vale desde effective_at salvo que se cancele.
objeto: policy_change · lo ve: solo el dueño · fase: auditoría
Agentes
agent.paused
Un agente se pausó (el dueño, la pausa de emergencia o la plataforma).
objeto: agent · lo ve: agente y dueño · fase: primera fase
agent.resumed
Un agente se reactivó.
objeto: agent · lo ve: agente y dueño · fase: primera fase
agent.created
Se creó un agente.
objeto: agent · lo ve: solo el dueño · fase: auditoría
agent.archived
Se archivó un agente (sus llaves se revocan).
objeto: agent · lo ve: solo el dueño · fase: auditoría
Llaves
api_key.created
Se creó una llave de API (nunca incluye el secreto).
objeto: api_key · lo ve: solo el dueño · fase: auditoría
api_key.rotated
Se rotó una llave; la vieja convive hasta grace_period_ends_at.
objeto: api_key · lo ve: solo el dueño · fase: auditoría
api_key.revoked
Se revocó una llave.
objeto: api_key · lo ve: solo el dueño · fase: auditoría
Destinos
destination.added
Se agregó un destino permitido (puede tener espera antes de valer).
objeto: destination · lo ve: solo el dueño · fase: auditoría
destination.removed
Se quitó un destino permitido.
objeto: destination · lo ve: solo el dueño · fase: auditoría
Avisos
webhook_endpoint.created
Se creó un destino de webhook.
objeto: webhook_endpoint · lo ve: solo el dueño · fase: auditoría
webhook_endpoint.paused
Un destino de webhook se pausó por fallos repetidos.
objeto: webhook_endpoint · lo ve: solo el dueño · fase: auditoría
notification_channel.added
Se agregó un canal de avisos (correo, Telegram...).
objeto: notification_channel · lo ve: solo el dueño · fase: auditoría
Sistema
webhook.test
Evento de prueba enviado a pedido del dueño; no hace falta suscribirse.
objeto: webhook_test · lo ve: solo el dueño · fase: primera fase