Webhook dei Pagamenti

Ricevi notifiche istantanee quando i pagamenti vengono creati, rilevati, confermati o incontrano problemi. I webhook sono il modo raccomandato per tracciare lo stato dei pagamenti.

Tipi di Evento

Eventi Ciclo di Vita Pagamento

Evento	Quando Emesso	Campi Chiave
`PAYMENT_CREATED`	Richiesta pagamento creata	amount, currency, paymentId
`PAYMENT_ADDRESS_ASSIGNED`	Indirizzo crypto allocato	address, coinSymbol, chainId
`PAYMENT_DETECTED`	Transazione vista sulla blockchain	txHash, amount, confirmations: 0
`PAYMENT_CONFIRMATION_UPDATE`	Cambio conteggio conferme	confirmations, required
`PAYMENT_CONFIRMED`	Conferme richieste raggiunte	txHash, confirmations
`PAYMENT_SETTLED`	Pagamento completamente elaborato	settledAmount, feeAmount
`PAYMENT_EXPIRED`	TTL scaduto senza pagamento	expiredAt
`PAYMENT_CANCELLED`	Cancellato manualmente	cancelledBy, reason
`PAYMENT_ABANDONED`	Utente ha chiuso il checkout	abandonedAt

Eventi Eccezione

Event	When Fired	Key Fields
`PAYMENT_EXPIRED_PARTIAL`	Pagamento parziale ricevuto prima della scadenza	expected, received
`PAYMENT_LATE_DETECTED`	Pagamento arrivato dopo scadenza	txHash, delay
`PAYMENT_REORG`	Transazione invalidata da reorg della chain	txHash (raro ma critico)

Payload Webhook

Tutti i webhook includono questi campi comuni:

Field	Description
`eventId`	Identificatore unico per idempotenza (evt_timestamp_hash)
`eventType`	Tipo di evento (es. PAYMENT_CONFIRMED)
`timestamp`	Timestamp ISO-8601 dell'emissione evento
`paymentRequestId`	L'ID del pagamento in SanPay
`externalId`	Il tuo riferimento ordine (passato durante la creazione)
`metadata`	Dati custom che hai incluso alla creazione del pagamento

{
  "eventId": "evt_1704556800000_abc123",
  "eventType": "PAYMENT_CONFIRMED",
  "timestamp": "2026-01-10T15:30:00.000Z",
  "tenantId": "tenant-uuid",
  "paymentRequestId": "pr_abc123",
  "externalId": "ORDER-12345",
  "metadata": { "orderId": "ORD-12345", "customerId": "C-789" },
  "txHash": "0xabc123def456...",
  "confirmations": 12
}

Header Richiesta

Header	Example Value
`Content-Type`	`application/json`
`X-Event-ID`	`evt_1704556800000_abc123`
`X-Event-Type`	`PAYMENT_CONFIRMED`
`X-Webhook-Signature`	`t=timestamp,v1=signature`
`User-Agent`	`SanPay-Webhook/1.0`

Policy di Retry

Ritentiamo le consegne webhook fallite con backoff esponenziale:

Tentativo	Ritardo
1	Immediato
2	1 minuto
3	5 minuti
4	30 minuti
5	2 ore
6	24 ore

Best Practice

Rispondi Velocemente

Rispondi 200 OK immediatamente. Elabora la logica pesante in modo asincrono per evitare timeout.

Gestisci i Duplicati

Usa eventId per idempotenza. Lo stesso evento può arrivare più volte a causa dei retry.

Verifica le Firme

Verifica sempre l'header X-Webhook-Signature prima di fidarti del payload.

Logga Tutto

Conserva i payload raw per debug. Potresti averne bisogno per la riconciliazione.

Gestisci Fuori Ordine

Gli eventi potrebbero arrivare fuori sequenza. Usa timestamp e state machine.