Öffentliche API-Webhooks sind ein neuer Dienst, der es ermöglicht, Benachrichtigungen über Änderungen in deinem Account zu erhalten, wodurch die Notwendigkeit einer ständigen Abfrage durch die öffentliche API von Rentman entfällt.

Im Wesentlichen sind Webhooks einfach URLs, die von Rentman aufgerufen werden, wenn etwas in deinem Account hinzugefügt, geändert oder gelöscht wird.

Man kann sie sich als Push-Benachrichtigungen für jedes Ereignis in deinem Account vorstellen - sei es das Hinzufügen eines neuen Projekts, die Bearbeitung eines Kontakts oder das Löschen einer Seriennummer. Wenn eines dieser Ereignisse eintritt, sendet Rentman einen Payload an die URL, die du festgelegt hast. Dieser Payload enthält Details über die hinzugefügte, geänderte oder gelöschte Entität, zusammen mit Hinweisen, wie man weitere Informationen von der öffentlichen API abrufen kann.

Hinweis: Die Verwendung von Webhooks erfordert technische Programmierkenntnisse und Erfahrung. Wenn du nicht über diese Kenntnisse verfügst, empfehlen wir dir, dich an einen externen Entwickler oder ein Unternehmen zu wenden. Bitte beachte, dass unser Support-Team in diesem Bereich nicht geschult ist und keine Unterstützung bei der Webhook-Implementierung leisten kann.

Öffentliche API-Webhooks einrichten

1. Um Webhooks zu altivieren, öffne das Konfigurationsmodul und wähle "Erweiterungen"
2. Scrolle nach unten zum Abschnitt Webhooks und klicke auf “Verbinden”
3. Das folgende Pop-up-Fenster wird daraufhin angezeigt:Hier musst du die URL angeben und bekommst ein Token. Im Feld URL gibst du an, welche URL von Rentman aufgerufen werden soll, wenn etwas in deinem Account erstellt, geändert oder gelöscht wird. Der Token wird stattdessen für die Generierung eines Digests verwendet, der auf Kundenseite verwendet werden sollte, um zu überprüfen, ob die Nachricht von Rentman stammt.
4. Klicke auf “Speichern” und schließe das Pop-up, um Webhooks zu aktivieren.

Öffentliche API-Webhooks richtig nutzen

Nachdem alle oben genannten Schritte befolgt wurden, ruft Rentman die angegebene URL auf, wenn in deinem Account etwas hinzugefügt, geändert oder gelöscht wird. In diesem Fall werden die Nachrichten an folgende Adresse gesendet https://mywebhookurl.com. 

Jede Nachricht hat ein einheitliches Format. Bei der Erstellung oder Aktualisierung sehen die Meldungen wie folgt aus:

{
  "account": "youraccountname",
  "user": { 
    "itemType": "Crew",
    "id": 33,
    "ref": "/crew/33"
  },
  "eventType": "create", 
  "itemType": "Contact", 
  "items": [ 
    {
        "id": 12014,
        "ref": "/contacts/12014",
        "parent": null
    }
  ],
  "eventDate": "2023-02-02T12:07:01+01:00"
}

{
  "account": "youraccountname",
  "user": {
      "itemType": "Crew",
      "id": 33,
      "ref": "/crew/33"
  },
  "eventType": "update",
  "itemType": "SerialNumber",
  "items": [
    {
        "id": 8367,
        "ref": "/serialnumbers/8367",
        "parent": {
            "id": 12792,
            "itemType": "Equipment",
            "ref": "/equipment/12792"
        }
    }
  ],
  "eventDate": "2023-02-02T12:03:25+01:00"
}

{
  "account": "youraccountname",
  "user": {
      "itemType": "Crew",
      "id": 33,
      "ref": "/crew/33"
  },
  "eventType": "delete",
  "itemType": "ContactPerson",
  "items": [
      10,
      31
  ],
  "eventDate": "2023-02-02T12:08:00+01:00"
}

/* example what a Digest header looks:
Digest: sha512=509072eee2c11804287bf807307ed360892053dde89c15ddacd9daa24c63c492963c089d54677598df4422f7d18cbd6a8ebca689841754e8ca44aee1054ddf0c
*/

// this is the full request body
$raw_body = file_get_contents('php://input');

//split value on '='
$digestParts = explode('=', $_SERVER['HTTP_DIGEST']);
$algo = digestParts[0];
$digest = digestParts[1];

// This is known by the client and Rentman only
$token= 'some_secret_key';
$clientGeneratedDigest = hash_hmac($algo, $raw_body, $token, false);

if($digest === $clientGeneratedDigest){
// The webhook call was made by Rentman
}
else{
// The webhook call was not made by Rentman
}

Was mache ich, wenn Webhook-URLs nicht mehr reagieren?

Wenn deine Webhook-URL nicht mehr reagiert, entweder aufgrund einer falschen Einrichtung oder aufgrund von Problemen mit deinem Endpunkt, hat Rentman ein Benachrichtigungssystem implementiert, um das Problem zu lösen.

Was bedeuten diese Benachrichtigungen?

Diese Benachrichtigungen sind nur für Mitarbeiter mit Zugriff auf das settingsKonfigurationsmodul. Stelle sicher, dass die entsprechenden Mitarbeiter in deinem Team Zugang zu diesem Modul haben, um informiert zu bleiben und eventuelle Probleme umgehend zu beheben.

Um diese Probleme zu beheben, kannst du Webhooks wieder aktivieren, indem du die URL im Abschnitt Webhooks im settings Konfigurationsmodul aktualisierst, so wie du es bei der erstmaligen Aktivierung von Webhooks tun würdest. 

[GIF here]

Rentman Tipp: Rentman-Tipp: Bitte stelle sicher, dass du eine gültige und funktionierende URL angibst, um eine ununterbrochene Webhook-Zustellung zu gewährleisten.