Integrazione · Webhook e API REST
Una chiave per account. Nessun OAuth da implementare.
Le stesse rotte che consuma la dashboard, eventi firmati in uscita con ritentativi e storico, e un endpoint per far entrare dati dai vostri sistemi.
Cosa avete a disposizione
Un header, e basta
Una chiave per account in un header. Niente flusso OAuth da implementare, niente token da rinnovare a mano.
Autenticazione
Più chiavi, revocabili una per una
Con etichetta, scadenza facoltativa e data di ultimo utilizzo. Revocarne una non tocca le altre, e l’effetto è immediato.
Chiavi
Le stesse rotte della dashboard
JSON diretto, senza involucri: quello che leggete è quello che consuma l’interfaccia, quindi non c’è una seconda verità da mantenere.
Formato
Ritentare non duplica
Con una chiave di idempotenza sulle scritture, la risposta riuscita viene conservata; la stessa chiave con un corpo diverso è un errore esplicito, non un secondo record.
Idempotenza
Il limite è negli header
Quante richieste restano e quando si azzera la finestra, su ogni risposta. Non c’è da indovinare quando rallentare.
Rate limit
Eventi firmati in uscita
Firma calcolata sul corpo grezzo, con il timestamp e un identificativo di consegna da usare come chiave di deduplicazione.
Firma
Ritentativi a scaletta
Sei tentativi distribuiti su circa quaranta ore. Un endpoint che risponde “andato per sempre” li ferma subito.
Retry
Storico delle consegne
Cosa è stato spedito, cosa ha risposto il vostro endpoint, tentativo per tentativo. Non un mistero da ricostruire dai vostri log.
Consegne
Rotazione del secret
Il precedente resta valido per un giorno, così si cambia chiave senza fermare niente e senza perdere eventi.
Rotazione
Un evento di prova
Per verificare firma e instradamento prima che passi un dato vero, e senza sporcare lo storico.
Test
Eventi in ingresso
Contatti, pratiche e note dai vostri sistemi, riconosciuti per identificativo esterno: alla seconda volta aggiornano, non duplicano.
Ingestion
Ogni ingresso è registrato
Payload ricevuto, esito, errore e il record che ne è uscito, consultabili dalla dashboard.
Registro
Cosa esce
Gli eventi sono quelli che ci sono, non quelli che potrebbero esserci.
Oggi in uscita ci sono i contatti e i commenti: creati, aggiornati, cancellati. L’elenco si interroga dall’API, così non si scopre da un endpoint muto che un evento non esiste.
- Su un aggiornamento arriva anche il valore precedente dei soli campi cambiati
- L’identificativo dell’evento è la chiave per non processarlo due volte
- La verifica va fatta sul corpo grezzo, confrontando le firme a tempo costante
- Il vostro endpoint deve rispondere entro dieci secondi: il resto lo fanno i ritentativi
I numeri dell’API
- Autenticazione
- un header, chiave per account
- Limite
- cento richieste al minuto per chiave
- Corpo massimo
- 10 MB
- Elementi per pagina
- fino a cento
Le altre integrazioni
Vi diciamo cosa si integra e cosa no.
Portateci il vostro sistema: guardiamo se serve un webhook, l’API, o niente del tutto.