VPOS.am Webhooks: eventi di pagamento firmati

Webhooks

Verificate X-VPOS-Signature sul corpo originale, salvate l’event id, restituite rapidamente 2xx e gestite le consegne ripetute in modo idempotente.

Versione

API v1

Ultima revisione

16 set 2026

Stato

Contratto pubblicato

Panoramica

Il contratto webhook pubblico di VPOS.am consegna l’evento firmato payment.status_changed con uno stato di pagamento verificato dal server.

HTTP / HMAC

Contratto di firma

Verifica l’HMAC con timestamp sul corpo grezzo della richiesta prima di analizzare il payload o modificare lo stato aziendale.

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	Contratto
Intestazione	`X-VPOS-Signature`
Valore firmato	`<timestamp>.<raw_request_body>`
Algoritmo	`HMAC-SHA256`
Tolleranza del timestamp	`5 minuti`
Timeout di consegna	`5 secondi`
Numero massimo predefinito di tentativi	`8 tentativi`
Pianificazione dei tentativi	`Esponenziale da 30 secondi, con limite di 1 ora`
Conferma	`Restituisci rapidamente una risposta 2xx`
Rotazione del segreto	`L’header può contenere più valori v1. Accetta l’evento solo se almeno uno corrisponde al segreto corrente o a un segreto di grace non scaduto.`
Elaborazione	`Verifica la firma, salva l’event id e poi accoda gli effetti secondari.`

Contratto pubblico dell’evento

Attualmente è documentato pubblicamente solo payment.status_changed. fiscalStatus fa parte di data.payment, ma non implica eventi pubblici fiscal o reconciliation separati.

Firma e riconsegna

Calcolate HMAC-SHA256 su <timestamp>.<raw_request_body> con il merchant webhook secret, rifiutate timestamp obsoleti ed eseguite le azioni downstream tramite una queue idempotente.

Come usare questa pagina

Webhooks aiuta ad allineare lo scenario di pagamento tra business, sviluppo e operations. Prima del lancio vanno definiti canale di vendita, route del provider, responsabilità webhook, verifica dello stato e supporto cliente dopo il pagamento.