Le Webhooks dell'API pubblica sono un servizio che ti consente di ricevere notifiche sulle modifiche al tuo account, eliminando la necessità di interrogare costantemente l'API pubblica di Rentman.
In sostanza, i webhooks sono semplicemente URL chiamati da Rentman ogni volta che qualcosa viene aggiunto, modificato o eliminato nel tuo account.
Pensaci come notifiche push per ogni evento nel tuo account: che si tratti di un nuovo progetto aggiunto, di un contatto modificato o di un numero di serie eliminato. Quando si verifica uno qualsiasi di questi eventi, Rentman invierà un payload all'URL che hai impostato. Questo payload contiene dettagli sull'entità aggiunta, modificata o eliminata, insieme a suggerimenti su come recuperare ulteriori informazioni dall'API pubblica.
Nota: L'utilizzo dei webhooks richiede competenze tecniche di programmazione ed esperienza. Se ti mancano queste competenze, ti consigliamo di cercare assistenza da uno sviluppatore o da un'azienda esterna. Tieni presente che il nostro team di supporto non è formato in questo settore e non può fornire assistenza con l'implementazione dei webhook.
Configurazione dei Webhooks dell'API pubblica
- Per abilitare i webhooks, vai al modulo di configurazione e seleziona "Estensioni"
- Scorri fino alla sezione Webhooks e clicca su "Connetti"
- Comparirà questo pop-up:Qui devi specificare URL e ti verrà fornito un Token. Il campo URL è dove specificare quale URL verrà chiamato da Rentman quando viene creato, modificato o eliminato qualcosa nel tuo account. Il Token, invece, verrà utilizzato per generare un digest che dovrebbe essere utilizzato lato client per verificare che il messaggio provenga da Rentman.
- Clicca su "Salva" e chiudi il pop-up per abilitare i Webhooks.
Padroneggiare i Webhooks dell'API pubblica
Dopo aver seguito tutti i passaggi sopra indicati, quando qualcosa viene aggiunto, modificato o eliminato nel tuo account, Rentman farà una chiamata all'URL specificato. In questo caso, verranno inviati messaggi a https://mywebhookurl.com.
Ogni messaggio segue un formato comune. Per creazioni o aggiornamenti, i messaggi avranno questo aspetto:
{
"account": "nome del tuo account",
"utente": {
"tipoElemento": "Equipaggio",
"id": 33,
"ref": "/equipaggio/33"
},
"tipoEvento": "crea",
"tipoElemento": "Contatto",
"elementi": [
{
"id": 12014,
"ref": "/contatti/12014",
"genitore": null
}
],
"dataEvento": "2023-02-02T12:07:01+01:00"
}
{
"account": "nome del tuo account",
"utente": {
"tipoElemento": "Equipaggio",
"id": 33,
"ref": "/equipaggio/33"
},
"tipoEvento": "aggiorna",
"tipoElemento": "NumeroSeriale",
"elementi": [
{
"id": 8367,
"ref": "/numeroseriali/8367",
"genitore": {
"id": 12792,
"tipoElemento": "Attrezzatura",
"ref": "/attrezzatura/12792"
}
}
],
"dataEvento": "2023-02-02T12:03:25+01:00"
}
elementi
:{
"account": "nome del tuo account",
"utente": {
"tipoElemento": "Equipaggio",
"id": 33,
"ref": "/equipaggio/33"
},
"tipoEvento": "elimina",
"tipoElemento": "PersonaDiContatto",
"elementi": [
10,
31
],
"dataEvento": "2023-02-02T12:08:00+01:00"
}
Il payload conterrà sempre questi componenti:
- account - nome dell'account da cui proviene il messaggio
- utente - ID e riferimento API pubblico dell'impiegato che ha avviato la modifica. Può essere nullo per azioni non eseguite dagli utenti, come quando un documento viene firmato digitalmente
- eventType - creazione, aggiornamento o eliminazione
- itemType - tipo dell'elemento che è stato creato, aggiornato o eliminato. I tipi di elementi possibili sono:
- Appuntamento, EquipaggioAppuntamento, Accessorio, PosizioneStock, DisponibilitàEquipaggio, RigaFattura, Contatto, Contratto, CostoProgetto, NumeroSeriale, Fattura, File, Cartella, FunzioneProgetto, GruppoFunzioneProgetto, AttivitàRegistrazioneTempo, Registro, Subnoleggio, GruppoAttrezzatureSubnoleggio, AttrezzatureSubnoleggio, Attrezzatura, GruppoAttrezzatureProgetto, Equipaggio, Preventivo, PersonaDiContatto, EquipaggioProgetto, VeicoloProgetto, AttrezzatureProgetto, Progetto, RichiestaProgetto, AttrezzatureGruppo, FattoreTariffaEquipaggio, Riparazione, ScansioneMagazzino, ScannerMagazzino, ContenutoSetAttrezzature, Stato, Sottoprogetto, ClasseTassa, TipoProgetto, RegistrazioneTempo, Veicolo, MovimentoStock
Suggerimento Rentman: Puoi aggiungere il valore "ref" per interrogare facilmente l'utente che ha attivato il webhook, semplicemente aggiungendolo dopo l'URL API di base https://api.rentman.net. Allo stesso modo, puoi fare lo stesso con il valore "ref" di ciascun elemento nel payload.
-
elementi - Per creazioni e aggiornamenti, il messaggio contiene un array di oggetti, dove ciascun oggetto rappresenta un elemento creato/aggiornato. L'oggetto contiene l'ID dell'elemento, il riferimento API pubblico e anche un oggetto nidificato della stessa struttura, che punta al genitore, se esiste. Se non c'è un genitore, il valore di
genitore
è uguale anull
. Per le eliminazioni,elementi
è un array di interi, contenente gli ID degli elementi eliminati - dataEvento - data e ora in cui si è verificato l'evento
Validazione dell'autenticità del payload del webhook
/* esempio di come appare un'intestazione Digest:
Digest: sha512=509072eee2c11804287bf807307ed360892053dde89c15ddacd9daa24c63c492963c089d54677598df4422f7d18cbd6a8ebca689841754e8ca44aee1054ddf0c
*/
// questo è il corpo completo della richiesta
$raw_body = file_get_contents('php://input');
// dividere il valore su '='
$digestParts = explode('=', $_SERVER['HTTP_DIGEST']);
$algo = digestParts[0];
$digest = digestParts[1];
// Questo è conosciuto solo dal client e da Rentman
$token= 'some_secret_key';
$clientGeneratedDigest = hash_hmac($algo, $raw_body, $token, false);
if($digest === $clientGeneratedDigest){
// La chiamata webhook è stata fatta da Rentman
}
else{
// La chiamata webhook non è stata fatta da Rentman
}
Cosa fare se gli URL dei webhook non rispondono?
Se l'URL del webhook non risponde, a causa di un'impostazione errata o di problemi con l'endpoint, Rentman ha implementato un sistema di notifica per risolvere la situazione.
Cosa significano queste notifiche:
"Consegna dei webhook non riuscita" |
Se l´endpoint del tuo webhook continua a non rispondere, riceverai notifiche ad ogni decimo errore, fino a un massimo di 40 errori (ad esempio, dopo 10, 20, 30 e 40 errori). Tieni presente che questi errori devono essere consecutivi; una singola consegna riuscita azzera il conteggio degli errori. |
"Consegna dei webhook disabilitata a causa di errori continui" |
Dopo 50 errori consecutivi, disabiliteremo l'endpoint del tuo webhook per evitare di inviare webhook a un URL non funzionante. A questo punto, riceverai una notifica che ti informerà della disattivazione. |
Queste notifiche sono visibili solo ai membri del team che hanno accesso al modulo settingsConfigurazione. Assicurati che i membri appropriati del tuo team abbiano accesso a questo modulo per restare informati e risolvere eventuali problemi rapidamente.
Per risolvere questi problemi, puoi riattivare i webhook aggiornando l'URL nella sezione Webhooks del modulo settings Configurazione esattamente come faresti per abilitare i webhook per la prima volta.
[GIF here]
Suggerimento Rentman: assicurati di fornire un URL valido e funzionante per garantire una consegna continua dei webhook senza interruzioni.