"x-signature": "algorithm=SHA256withECDSA, keyId=2dcd5b38-78a1-47ea-a1c7-ed760403d88c, signature=jXt3fB8v7v/ea2MGUXj+c+FCUF6su51lCnH1DK/0tm444f6508K8FGtAFqVAmH/faJnzvE1IxLtcR6sj8M9b0g=="Un webhook può essere usato per notificare eventi ad un’altra applicazione. Gli webhook sono generalmente scatenati da qualche evento, ad esempio per notificare all’applicazione un cambiamento di stato di un’entità.
Esistono due concetti per notificare le modifiche di un’applicazione. Uno è il polling e l’altro è il pushing. Il polling non è ottimale perché se l’aggiornamento non esiste, il polling è sprecato. Per questo motivo si ricorre al push degli aggiornamenti. Webhooks è un concetto in base al quale l’applicazione interessata agli aggiornamenti riceve una notifica tramite una richiesta HTTP. Ciò significa che l’applicazione può registrarsi per determinati eventi e inviare una richiesta HTTP quando si verifica tale evento.
Tutti i dettagli della configurazione possono essere impostati all’interno dello spazio Spazio > Impostazioni > Aspetti Generali > Ascoltatori Webhook. È possibile definire qui l’URL e scegliere tra i diversi eventi per i quali si desidera ricevere una chiamata HTTP.
All URLs you want a webhook delivered to are configured centrally inside Spazio > Impostazioni > Aspetti Generali > URL webhook. Fare clic per aggiungere un URL webhook. La gestione centralizzata degli URL consente di gestire più facilmente le modifiche agli URL, in modo da non dover intervenire su ogni configurazione degli ascoltatori di webhook.
È anche possibile creare programmaticamente un URL webhook tramite la nostra API o SDK: ad esempio.
|
Warning
|
Aggiornamento importante sul meccanismo di firma dei webhook: Si consiglia vivamente di iniziare a integrare il nuovo meccanismo di firma negli webhook il prima possibile. Ciò garantirà una transizione graduale quando la funzione diventerà obbligatoria. Dopo il periodo di transizione, il precedente processo di gestione dei webhook sarà gradualmente eliminato. |
Perché abbiamo implementato la firma dei payload dei webhook
Nel nostro costante impegno a sostenere i più alti standard di sicurezza e integrità dei dati, abbiamo implementato un robusto meccanismo di firma del payload per i nostri webhook. Questo approccio si basa sull’uso della crittografia a chiave pubblica e privata, combinata con algoritmi di hashing sicuri, per autenticare e verificare i dati inviati.
Ecco come questo processo migliora la sicurezza e l’affidabilità dei nostri webhook:
Generazione e gestione di coppie di chiavi di crittografia Webhook:
Generiamo una coppia di chiavi crittografiche composta da una chiave privata e una pubblica. La chiave privata, memorizzata in modo sicuro nel nostro database, viene utilizzata per firmare i payload dei webhook.
La chiave pubblica viene condivisa con l’utente per consentire la verifica di queste firme e può essere recuperata tramite il keyId generato in modo univoco, utilizzando l’endpoint read nel
Servizio di crittografia degli webhook.
Processo di firma:
Ogni volta che viene inviato un payload di webhook, viene innanzitutto eseguito un hash del payload utilizzando l’algoritmo di hashing SHA-256, integrato dall’algoritmo di firma digitale a curva ellittica (ECDSA), per creare una rappresentazione distinta e sicura del contenuto del payload.
Questo hash viene poi crittografato con la nostra chiave privata, formando una firma digitale. Questa firma digitale è fondamentale per garantire l’integrità e l’autenticità del payload. Aggiungiamo quindi questa firma alla richiesta HTTP in uscita del webhook, sotto forma di un’intestazione (header) personalizzata denominata x-signature.
Il valore di questa intestazione include dettagli essenziali come l’algoritmo utilizzato (SHA256withECDSA), un identificativo univoco della chiave (keyId) e l’effettiva firma (signature).
Questa intestazione svolge un ruolo fondamentale nel consentire al destinatario del webhook di verificare l’autenticità dei dati ricevuti utilizzando le informazioni fornite, assicurando che il payload provenga effettivamente da una fonte affidabile e non sia stato alterato durante il transito.
Trasmissione sicura del Payload:
Il payload, insieme alla sua firma digitale, viene trasmesso al destinatario. Questo processo garantisce che il payload vi arrivi esattamente come lo abbiamo inviato, senza manomissioni o modifiche non autorizzate.
Verifica da parte dei clienti:
Quando si riceve un payload webhook, è possibile verificarne l’autenticità e l’integrità. Eseguendo l’hashing del payload con lo stesso metodo e decifrando la firma con la chiave pubblica recuperata, si può confermare che il payload è legittimo e inalterato. Una corrispondenza tra l’hash calcolato e la firma decifrata indica che il payload è autentico ed è stato effettivamente inviato dal nostro sistema.
Il processo di verifica dell’autenticità e dell’integrità del payload webhook ricevuto è condotto in modo programmatico attraverso il nostro SDK. Al ricevimento di un payload webhook, l’applicazione può utilizzare i metodi SDK forniti per convalidare il payload.
"x-signature": "algorithm=SHA256withECDSA, keyId=2dcd5b38-78a1-47ea-a1c7-ed760403d88c, signature=jXt3fB8v7v/ea2MGUXj+c+FCUF6su51lCnH1DK/0tm444f6508K8FGtAFqVAmH/faJnzvE1IxLtcR6sj8M9b0g=="Un ascoltatore può ascoltare i cambiamenti di stato di particolari entità. Ciò significa che quando un’entità passa allo stato specificato, l’URL verrà invocato. Solo determinate entità sono abilitate a essere sottoscritte da un ascoltatore di webhook. Un ascoltatore di webhook può essere creato in Spazio > Impostazioni > Aspetti Generali > Ascoltatori di webhook.
È anche possibile creare programmaticamente un ascoltatore utilizzando la nostra API o SDK: esempio qui.
Un registro di tutti gli webhook innescati può essere visualizzato al Spazio > Impostazioni > Aspetti Generali > Invocazioni webhook. Facendo clic sull’invocazione è possibile vedere l’errore nel caso in cui il webhook non sia riuscito, compresa la risposta ricevuta dal server.
|
Note
|
Cerchiamo di consegnare l’evento finché non raggiungiamo un certo numero di tentativi. L’intervallo di tempo tra i tentativi viene aumentato dopo ogni tentativo. Quando la consegna continua a fallire, l’ascoltatore viene disattivato, per evitare di invocare ulteriormente un ascoltatore potenzialmente guasto. |
La richiesta HTTP inviata per il cambio di stato di un’entità contiene i seguenti dati:
eventId: Un ID univoco che identifica il cambiamento di stato. Sarà sempre diverso per ogni notifica.
entityId: L’ID dell’entità che è stata modificata.
listenerEntityId: L’entità ascoltatrice indica quale tipo di entità è stata modificata.
listenerEntityTechnicalName: Il nome tecnico dell’entità ascoltatrice fornisce un nome per il tipo di entità.
spaceId: L' ID dello spazio a cui appartiene l’entità che è stata modificata.
webhookListenerId: L’ID dell’ascoltatore.
timestamp: L’ora in cui si è verificato il cambiamento di stato.
{
"eventId": 138833842,
"entityId": 63762876,
"listenerEntityId": 1472041829003,
"listenerEntityTechnicalName": "Transaction",
"spaceId": 30140,
"webhookListenerId": 285874,
"timestamp": "2022-08-23T14:20:53+0000"
}Una volta ricevuta la notifica sul vostro URL, dovrete chiamare la nostra API per leggere lo stato modificato dell’entità. Questo ha il vantaggio principale di potervi notificare anche su URL non protetti e di non dover scambiare dati sensibili direttamente con il vostro sistema.
|
Note
|
Raccomandiamo l’utilizzo di HTTP(s), quindi una connessione criptata, se intendete utilizzare il payload certificato tramite firma digitale, spiegata sopra. |
Per leggere lo stato dell’entità e ulteriori dettagli, si deve usare il corrispondente endpoint read nella
Documentazione API utilizzando l’elemento entityId.
La richiesta HTTP inviata per un cambiamento di stato di un’entità include ora un campo aggiuntivo state, che fornisce informazioni sull’aggiornamento dello stato dell’entità monitorata. Questo miglioramento è il risultato dell’implementazione del nostro meccanismo di crittografia dei webhook.
Il campo payload state fornisce informazioni dirette sull’aggiornamento dello stato dell’entità, rendendo superflue ulteriori chiamate API per recuperare lo stato dell’entità.
{
"eventId": 138833842,
"entityId": 63762876,
"listenerEntityId": 1472041829003,
"listenerEntityTechnicalName": "Transaction",
"spaceId": 30140,
"webhookListenerId": 285874,
"timestamp": "2022-08-23T14:20:53+0000",
"state": "PROCESSING"
}Con l’introduzione del campo state, una volta ricevuta la notifica al proprio endpoint, si riduce notevolmente la necessità di effettuare ulteriori chiamate API al nostro sistema per leggere lo stato dell’entità modificata. Questo miglioramento non solo snellisce il processo, ma mantiene anche la sicurezza, riducendo al minimo lo scambio di dati sensibili.
Affinché gli webhook funzionino correttamente, è importante che la configurazione del firewall e del server consenta la comunicazione dai nostri server. Questo documento fornisce tutte le informazioni necessarie per configurare i firewall in modo da consentire il traffico tra la vostra infrastruttura e i nostri servizi, riducendo così al minimo il rischio di errori/problemi di comunicazione.
Questo documento presuppone che l’esercente abbia familiarità con le procedure di configurazione di firewall, router o qualsiasi altro dispositivo utilizzato per bloccare il traffico sulla rete dell’esercente.
Il seguente elenco contiene gli indirizzi IP che devono essere inseriti nella white list per consentire la comunicazione tra la vostra infrastruttura e la nostra piattaforma. La richiesta HTTP viene inviata da questi indirizzi IP.