API: automazione invece di copia/incolla
Le API aiutano a standardizzare i workflow: emissione certificati, aggiornamento metadati, recupero stati. Obiettivo: integrazioni solide in produzione, con ID chiari, stati tracciabili e errori utili.
Webhooks: eventi in (quasi) tempo reale
I webhooks sono callback: quando accade qualcosa (certificato finalizzato, stato cambiato, verifica attivata), il tuo sistema viene notificato automaticamente. Riduce il polling. Funzionano al meglio come stream di eventi: piccoli, espliciti, ripetibili.
Eventi: piccoli, chiari, auditabili
Meglio evitare payload enormi: eventi compatti (tipo evento, ID oggetto, timestamp, opzionalmente versione/revisione). I dettagli si possono recuperare via API quando serve. Questo rende l’integrazione più stabile.
Sicurezza: firme e verifica della fonte
Regola d’oro: non fidarti mai dei webhooks in ingresso senza verifica. Pattern comuni: header firmati (HMAC) per validare l’origine. A seconda del contesto: restrizioni IP, rate limit e gestione accurata dei segreti aumentano la protezione.
Affidabilità: retries, idempotenza, ordine
Nella pratica, i webhooks possono arrivare duplicati o fuori ordine. I receiver devono essere idempotenti: elaborare lo stesso event due volte non deve causare problemi. Importanti anche retry, timeout e gestione errori transitori (5xx).
Versioning: cambiamenti prevedibili
Le interfacce evolvono. Versioning e compatibilità riducono i rischi: versioni API esplicite, schemi eventi stabili e preavviso per breaking changes.
In sintesi
- API = standardizzare workflow; webhooks = ricevere eventi automaticamente.
- Eventi piccoli; dettagli via API quando serve.
- Verifica sempre i webhooks (HMAC) e gestisci bene i segreti.
- Receiver idempotenti: i duplicati devono essere sicuri.
- Versioning = meno rischi operativi.
Sicurezza & Privacy: /it/security
Contatto: /it/contact