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
}
Questo articolo ti è stato utile?
Utenti che ritengono sia utile: 0 su 0

Articoli in questa sezione