Parti dal contratto operativo
Definisci trigger, record sorgente, destinazione, mapping, tempo atteso e responsabile. Per lo stock, stabilisci quale sistema possiede la quantità disponibile. Per gli ordini, definisci idoneità, cancellazioni e identificatore comune.
Separa trasporto e regole di business
Acquisire dati, validarli e applicare una regola commerciale sono responsabilità diverse. Separarle rende le eccezioni ispezionabili ed evita di confondere un outage API con una condizione commerciale rifiutata.
Progetta per duplicati ed eventi mancanti
Shopify specifica che l’ordine dei webhook non è garantito, raccomanda la deduplica tramite webhook ID e suggerisce riconciliazioni periodiche perché alcune consegne possono mancare. Il workflow deve quindi memorizzare gli ID, essere idempotente e ricontrollare la sorgente.
Rendi visibile il guasto
Registra input, esito, timestamp e stato del retry. Ritenta gli errori transitori con limiti e backoff; manda quelli permanenti a revisione. Una risposta HTTP positiva non prova sempre il completamento dell’operazione di business.
Checklist
1. Nomina la fonte autorevole. 2. Definisci ID stabili. 3. Valida prima di scrivere. 4. Rendi idempotenti i retry. 5. Aggiungi alert e owner. 6. Riconcilia sorgente e destinazione. 7. Testa il recovery.