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 modulo di configurazione e seleziona "Estensioni"
2. Scorri fino alla sezione Webhooks e clicca su "Connetti"
3. 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.
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"
}

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

[GIF here]

Suggerimento Rentman: assicurati di fornire un URL valido e funzionante per garantire una consegna continua dei webhook senza interruzioni.