VPOS.am Webhooks: eventos de pago firmados

Webhooks

Verifique X-VPOS-Signature sobre el cuerpo original, guarde el event id, devuelva 2xx rápidamente y procese las entregas repetidas de forma idempotente.

Versión

API v1

Última revisión

16 sept 2026

Estado

Contrato publicado

Resumen

El contrato público de webhooks de VPOS.am entrega el evento firmado payment.status_changed con un estado de pago verificado por el servidor.

HTTP / HMAC

Contrato de firma

Verifica el HMAC con marca de tiempo sobre el cuerpo original de la solicitud antes de analizar el payload o cambiar el estado de negocio.

X-VPOS-Event-Id: <event_id>
X-VPOS-Event-Type: payment.status_changed
X-VPOS-Webhook-Timestamp: <unix_timestamp>
X-VPOS-Signature: t=<unix_timestamp>,v1=<current_secret_hmac>[,v1=<grace_secret_hmac>]

signed_payload = <timestamp>.<raw_request_body>
signature = HMAC-SHA256(webhook_secret, signed_payload)

Campo	Contrato
Cabecera	`X-VPOS-Signature`
Valor firmado	`<timestamp>.<raw_request_body>`
Algoritmo	`HMAC-SHA256`
Tolerancia del timestamp	`5 minutos`
Tiempo límite de entrega	`5 segundos`
Máximo de intentos predeterminado	`8 intentos`
Programa de reintentos	`Exponencial desde 30 segundos, con límite de 1 hora`
Confirmación	`Devuelve rápidamente una respuesta 2xx`
Rotación del secreto	`La cabecera puede contener varios valores v1. Acepta el evento solo si al menos uno coincide con el secreto actual o con un secreto de gracia no vencido.`
Procesamiento	`Verifica la firma, guarda el event id y después encola los efectos secundarios.`

Contrato público del evento

Actualmente solo payment.status_changed está documentado públicamente. fiscalStatus forma parte de data.payment, pero no implica eventos públicos separados de fiscalización o conciliación.

Firma y reentrega

Calcule HMAC-SHA256 sobre <timestamp>.<raw_request_body> con el merchant webhook secret, rechace timestamps antiguos y ejecute las acciones downstream mediante una cola idempotente.

Cómo usar esta página

Webhooks ayuda a alinear el escenario de pago entre negocio, desarrollo y operaciones. Antes del lanzamiento conviene fijar el canal de venta, la ruta del proveedor, responsables de webhook, verificación de estado y soporte al cliente tras el pago.