Registra solo gli eventi di cui hai bisogno
Crea un endpoint conPOST /v3/webhooks. Iscriviti solo agli eventi documentati che guidano la tua integrazione. Questo esempio usa transfer.state_changed.
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-idsvix-timestampsvix-signature
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. Usaresource.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}:
Recupera le consegne
UsaGET /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.