Quattro superfici
API, webhook, SDK widget e workflow sono contratti diversi
Parti da una transazione: creare contatto CRM, aggiornare ticket o archiviare un messaggio. Definisci mittente, destinatario, trigger, campi, latenza, errore e system of record.
Richiedi URL, versione, auth, scope, endpoint, catalogo eventi, payload, paginazione, limiti, changelog, deprecation e supporto per quel caso.
| Superficie | Finalità | Non include automaticamente |
|---|---|---|
| API prodotto | leggere/scrivere record ed eseguire azioni | eventi real-time o interfaccia |
| Webhook | notificare un endpoint per eventi scelti | query libere, storico completo o exactly-once |
| SDK widget | controllare browser, identità, aspetto o tracking | API server per agenti, export o compliance |
| Power Platform | orchestrare Teams, connettori e sistemi | API nativa generale o connettore pronto per ogni CRM |
Matrice prove
Cosa dimostrano le fonti ufficiali
| Prodotto | Documentato | Limite pre-acquisto |
|---|---|---|
| WebChat | keyword, connettore Teams, Power Automate e sistemi opzionali | nessuna API generale, webhook prodotto o SDK provato pubblicamente |
| Chatwoot | API Application, Client, Platform; webhook account firmati HMAC | testare token, classe API, Cloud/self-hosted e consegna |
| Tidio | OpenAPI, Widget SDK e webhook firmati con topic, versione e ID | webhook Plus/Premium owner/admin; cambi OpenAPI senza webhook |
| LiveChat | API Agent/Customer, Web/RTM, webhook registrati e scope | validare app, OAuth/PAT, ruoli, filtri, piano e versione |
Operazioni
At-least-once richiede idempotenza e riconciliazione
Tidio documenta duplicati, ordine non garantito, ID unico e nessun webhook per modifiche OpenAPI. LiveChat indica ack breve e retry limitati. Chatwoot documenta firma, timestamp e delivery, ma il PoC deve provare retry e ordine della release.
HTTP verdi non bastano. Misura ricevuti, verificati, deduplicati, processati, falliti e riconciliati con ID business.
- Rispondi 2xx subito e processa poi con coda asincrona.
- Verifica firma su body grezzo, timestamp e finestra; ruota i secret.
- Deduplica con delivery/webhook/event ID e rendi ogni effetto retry-safe.
- Ordina per tempo business e ID stabile, non solo per arrivo.
- Metti errori in quarantena/dead letter, allerta e consenti replay controllato.
- Riconcilia via API: eventi possono tardare, duplicarsi, filtrarsi o mancare.
- Versiona schema e consumer; tollera campi nuovi e blocca requisiti mancanti.
Sicurezza e privacy
Minimizzare token, payload e diritti di scrittura
Una firma valida prova origine e integrità sotto il secret, non autorizzazione business ad agire.
Con Teams/Power Platform includi flow owner, connessioni, DLP, ambienti, licenze e ritorno al visitatore.
- Separa test/prod, secret webhook, token API e identità interattive.
- Concedi solo scope necessari; accesso globale richiede motivazione.
- Mappa nome, email, telefono, testo, allegati, browser e note interne.
- Cifra coda, log, replay e secret; maschera dati nella telemetria.
- Proteggi write-back con stato, allowlist, approvazione e audit.
- Definisci retention, accesso e cancellazione per eventi, errori, export e backup.
Collaudo
Otto test prima della scelta
- 01
Fissare contratto
Caso, record, versione, endpoint, eventi, campi e latenza.
- 02
Negare accesso
Token scaduto, errato, insufficiente e account altrui falliscono.
- 03
Verificare firma
Body alterato, tempo vecchio, secret falso e replay non agiscono.
- 04
Duplicare
Stesso evento ripetuto/parallelo ha un solo effetto.
- 05
Rompere ordine
Update prima di create, close tardivo e messaggi simultanei.
- 06
Forzare guasto
Timeout, 500, coda, target e rate limit con retry, alert, recovery.
- 07
Riconciliare buco
Perdere webhook o usare origine API e ritrovare record.
- 08
Provare exit
Ruotare secret, revocare app, cancellare webhook, export delta ed eliminare copie.