In sostanza, i webhook sono semplicemente URL che Rentman chiama ogni volta che qualcosa viene aggiunto, modificato o eliminato nel tuo account.

Puoi pensarli come notifiche push per ogni evento nel tuo account: che si tratti dell’aggiunta di un nuovo progetto, della modifica di un contatto o dell’eliminazione di un numero di serie. Quando uno di questi eventi si verifica, Rentman invia un payload all’URL che hai configurato. Questo payload include i dettagli sull’entità aggiunta, modificata o eliminata, oltre a indicazioni su come ottenere ulteriori informazioni tramite l’API pubblica.

Configurazione dei webhook dell'API pubblica

1. Per abilitare i webhooks, vai al modulo Configurazione e seleziona "Integrazioni";
2. scorri fino alla sezione Webhook e clicca su "Connetti";
3. comparirà questo pop-up:Qui devi specificare un URL e ti verrà fornito un token. Nel campo URL, devi indicare l’indirizzo a cui Rentman invierà le notifiche ogni volta che qualcosa viene creato, modificato o eliminato nel tuo account. Il token, invece, verrà utilizzato per generare un codice di verifica che potrai utilizzare lato client per assicurarti che il messaggio provenga effettivamente da Rentman;
4. clicca su "Salva" e chiudi il pop-up per abilitare i webhook.

Padroneggiare i webhook 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"
}

{
  "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"
}

/* 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:

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.