Skip to main content
Usa i webhook per reagire ai cambiamenti asincroni. La consegna e’ at-least-once, quindi eventi duplicati, in ritardo e fuori ordine sono normali.

Registra solo gli eventi di cui hai bisogno

Crea un endpoint con POST /v3/webhooks. Iscriviti solo agli eventi documentati che guidano la tua integrazione. Questo esempio usa transfer.state_changed.
Salva il data.id della risposta come WEBHOOK_ID. Apri il portale restituito da GET /v3/webhooks/portal, recupera il signing secret di questo endpoint e conservalo separatamente dalla chiave API in un secret manager.

Verifica prima di parsare

Swipelux consegna le nuove integrazioni webhook tramite Svix. Verifica il body grezzo della richiesta con il signing secret dell’endpoint e questi header:
  • svix-id
  • svix-timestamp
  • svix-signature
Non parsare JSON o causare side effect prima che la verifica abbia successo.
Rifiuta le richieste con firme mancanti o non valide. Mantieni disponibile il body grezzo finche’ la verifica non e’ completa.

Persisti, conferma e poi processa

Imposta un vincolo di univocita’ sull’id dell’envelope. Persisti l’envelope verificato, restituisci 2xx prontamente, poi processalo in modo asincrono. Se l’ID evento esiste gia’, conferma la consegna senza ripetere side effect gia’ completati. Riprendi il lavoro locale pending o fallito tramite la tua coda di retry. Non usare il campo attempt dell’envelope come chiave di deduplicazione o come contatore di retry di trasporto.

Rileggi lo stato corrente

L’ordine dei webhook non e’ una cronologia autorevole della risorsa. Usa resource.type e resource.id per localizzare l’oggetto, poi recupera il suo stato corrente prima di aggiornare il tuo sistema. Per un evento di transfer, chiama GET /v3/transfers/{transferId}:
Guida lo stato visibile al cliente e le azioni downstream dalla risposta API corrente. Progetta i side effect in modo che restino sicuri se due worker processano eventi correlati in ordine diverso.

Recupera le consegne

Usa GET /v3/webhooks/portal per aprire i log di consegna, ritentare consegne fallite o avviare un replay manuale. Ogni replay deve passare per la stessa verifica di firma e per la stessa inbox durevole. Per recuperare dopo un downtime, ripeti la finestra interessata e rileggi ogni risorsa referenziata. Gli ID evento completati restano no-op; i record incompleti riprendono in modo asincrono. Successivamente, verifica in sandbox le consegne duplicate e fuori ordine, poi completa la checklist Go live.