Webhooks dell'API pubblica

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

  1. Per abilitare i webhooks, vai al Screenshot 2023-11-23 at 15.56.05.png modulo di configurazione e seleziona "Estensioni"
  2. Scorri fino alla sezione Webhooks e clicca su "Connetti"image-20231120-112332.png
  3. Comparirà questo pop-up:image-20231120-112310.pngQui 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.
  4. 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"
}
Gli elementi più complessi, come i Sottoprogetti o i gruppi di attrezzature pianificate, possono avere strutture di messaggi più estese, che includerebbero anche puntatori agli elementi genitori.
{
"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"
}
Quando un elemento viene eliminato, il messaggio contiene dettagli leggermente diversi nella sezione 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:
Tipi di elementi possibili
  • 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 a null. 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"

image (1).png

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"

image (2).png

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.  

Questo articolo ti è stato utile?
Utenti che ritengono sia utile: 1 su 1

Articoli in questa sezione