Webhooks verwalten

In diesem Abschnitt wird erläutert, wie Sie Webhooks verwalten, einschließlich Einrichtung, Bearbeitung, Protokollierung, Testen, Entfernen und Status.

Webhooks einrichten

Mit diesen Schritten können Sie einen Webhook einrichten, einschließlich des Hinzufügens des Webhooks, der Bereitstellung seines Endpunkts und des Stellens einer Anfrage auf Verifizierung Ihres Webhooks.

Einen Webhook hinzufügen

Stellen Sie die folgende POST-Anfrage mit den Parametern des Anfrage-Bodys, um einen Webhook hinzuzufügen:

curl -X POST \
  -H 'X-API-KEY:<your_api_key>' \
  -H "Content-type:application/json" \
  -d '{"name":"<your_webhook_name>", \
       "url":"<your_webhook_url>", \
'https://<your_company>.manage.iotium.io/api/v1/webhook'

Die Antwort beinhaltet folgende Informationen:

{
  "id":"<your_webhook_id>"
  "name":"<your_webhook_name>",
  "url":"<your_webhook_url>",
  "is_enabled":false,
  "secret":"<your_webhook_client_secret>"
}

Speichern Sie den Wert des Felds Secret. Dieser ist erforderlich, um den Webhook zu verifizieren.

Wenn in dem Feld is_enabled false eingestellt ist, weist dies darauf hin, dass der Webhook deaktiviert ist. Sie müssen die Verifizierung des Webhooks erfolgreich abschließen, um diesen zu aktivieren. In Understanding Webhook States erhalten Sie Informationen über die Status von Webhooks.

Sie können höchstens drei Webhooks hinzufügen.

Endpunkt Ihres Webhooks bereitstellen

Entwickeln und implementieren Sie Ihre Anwendung, die Webhook-Benachrichtigungen von ioTium erhalten wird. Implementieren Sie Ihre Anwendung mit einem öffentlich verfügbaren HTTPS-Endpunkt für die Webhook-URL. Ein HTTPS-Endpunkt mit einem selbstsignierten Zertifikat wird nicht unterstützt. Nutzen Sie stattdessen ein gültiges SSL-/TLS-Zertifikat einer weltweit anerkannten Zertifizierungsstelle.

Anfrage auf Verifizierung Ihres Webhook-Endpunkts stellen

Vor der Aktivierung des Webhooks bestätigt ioTium, dass Ihre Anwendung Benachrichtigungen an diese URL erhalten möchte. Wenn Sie eine Anfrage auf Verifizierung Ihres Webhook-Endpunkts stellen, generieren wir einen Challenge-Code und stellen eine HTTP-GET-Anfrage an Ihren Webhook-Endpunkt mit dem Challenge-Code als Abfrageparameter. Die GET-Anfrage hat die folgenden ioTium-spezifischen Header:

Ihr Webhook-Endpunkt sollte wie folgt auf die GET-Anfrage antworten:

1. Extrahierung des Zeitstempels aus dem Header-Feld X-Iotium-Zeitstempel und des Challenge-Codes aus dem Abfrageparameter.
2. Antwort auf den Challenge-Code auf folgende Art und Weise:

   challenge_response = Hex-encoded(HMACSHA256(<>,>,>

   Das Secret ist der Wert des Felds Secret, den Sie aus der Antwort auf die POST-Anfrage zum Hinzufügen des Webhooks gespeichert haben.
   Dies ist ein Ausschnitt eines Beispielcodes in Python (Version 3.8.2) der Antwort auf den Challenge-Code:
   JavaJava

   def genChallengeResponse(secret:str, timestamp:str, challenge:str) -> str:
    import hmac
    import hashlib
    message:str = "%s.%s" % (timestamp, challenge)
    return hmac.new(secret.encode(), message.encode(), hashlib.sha256).hexdigest()

   Dies ist ein Ausschnitt eines Beispielcodes in Java (Version 1.8.0_191) der Antwort auf den Challenge-Code:

   import java.nio.charset.Charset;
   import java.security.GeneralSecurityException;
   import javax.crypto.Mac;
   import javax.crypto.spec.SecretKeySpec;
   
   public String getChallengeResponse(String secret, String timestamp, String challenge) {
        String HMAC_SHA256_ALGORITHM = "HmacSHA256";
        String hmac_hex = null;
        try {
          SecretKeySpec signingKey = new    SecretKeySpec(secret.getBytes(Charset.defaultCharset()),
                       HMAC_SHA256_ALGORITHM);
         Mac mac = Mac.getInstance(HMAC_SHA256_ALGORITHM);
         mac.init(signingKey);
         String message = timestamp.concat(".").concat(challenge);
         byte[] rawHmac = mac.doFinal(message.getBytes(Charset.defaultCharset()));
               hmac_hex = bytesToHex(rawHmac);
           } catch (GeneralSecurityException e) {
               throw new IllegalArgumentException();
           }
           return hmac_hex;
       }
   
   public String bytesToHex(byte[] bytes) {
        char[] hexArray = "0123456789abcdef".toCharArray();
        char[] hexChars = new char[bytes.length * 2];
        for (int j = 0; j < bytes.length; j++) {
             int v = bytes[j] & 0xFF;
           hexChars[j * 2] = hexArray[v >>> 4];
           hexChars[j * 2 + 1] = hexArray[v & 0x0F];
       }
         return new String(hexChars);
   }

   3. Antwort innerhalb von drei Sekunden mit einem 200 OK Status mit dem Challenge-Code und der Antwort auf den Challenge-Code im Nachrichtenkörper:
   ShellShell

   {
    	  "challenge":"",>",>">">

Anfrage auf Verifizierung Ihres Webhook-Endpunkts an Secure Edge stellen

Wenn Ihr Webhook-Endpunkt bereit zur Verifizierung ist, stellen Sie eine POST-Anfrage an uns, um ihn verifizieren zu lassen. Wir verifizieren Ihren Webhook, indem wir eine GET-Anfrage an die Webhook-URL senden. Falls wir in der Lage sind, die Antwort auf den Challenge-Code zu verifizieren, ist die Einrichtung des Webhooks abgeschlossen.

Stellen Sie die folgende POST-Anfrage an Secure Edge, um den Webhook verifizieren zu lassen:

curl -X POST \
  -H 'X-API-KEY:<your_api_key>' \
  -H "Content-type:application/json" \
'https://<your_company>.manage.iotium.io/api/v1/webhook/<your_webhook_id>/verify

Wir stellen anschließend eine GET-Anfrage an Ihren Webhook-Endpunkt mit einem Challenge-Code als Abfrageparameter. Eine solche Anfrage sieht wie folgt aus:

curl -X GET \
  -H '<your_additional_headers>' \
  -H "Content-type:application/json" \
  -H "X-Iotium-Timestamp:<TIMESTAMP>" \
'<your_webhook_url>?challenge=<your_webhook_challenge>'

Für eine erfolgreich Verifizierung muss die Antwort auf die obige GET-Anfrage folgende Anforderungen erfüllen:

• Die Antwort wird innerhalb von drei Sekunden mit einem 200 OK Status erhalten.
• Der Nachrichtenkörper beinhaltet den Challenge-Code und die Antwort auf den Challenge-Code.
• Die Antwort auf den Challenge-Code ist gültig.

Bei einer erfolgreichen Verifizierung beinhaltet die Antwort auf Ihre POST-Anfrage folgende Informationen:

{
  "id":"<your_webhook_id>",
  "message":"Webhook verification successful",
  "status":"SUCCESS"
}

Bei einer fehlgeschlagenen Verifizierung beinhaltet die Antwort auf Ihre POST-Anfrage folgende Informationen:

{
  "id":"<your_webhook_id>",
  "message":"Webhook verification failed",
  "status":"FAILED"
}

Falls Sie versuchen, einen bereits verifizierten Webhook zu verifizieren, erhalten Sie eine Fehlermeldung.

Bei einer erfolgreichen Verifizierung des Webhooks ändert sich dessen Status zu „Aktiviert“ und er kann für Meldungen genutzt werden. Bei einer fehlgeschlagenen Verifizierung bleibt der Status des Webhooks „Deaktiviert“ und er kann nicht genutzt werden.

Webhooks hinzufügen

Stellen Sie eine PUT-Anfrage mit einem oder mehreren der folgenden Parameter, um einen Webhook hinzuzufügen.

Stellen Sie beispielsweise folgende PUT-Anfrage, um Änderungen an Ihrer Webhook-URL vorzunehmen:

curl -X PUT \
  -H 'X-API-KEY:<your_api_key>' \
  -H "Content-type:application/json" \
  -d '{"url":"<your_new_webhook_url>"}' \
'https://<your_company>.manage.iotium.io/api/v1/webhook/<your_webhook-id>

Die Antwort beinhaltet folgende Informationen:

{
  "id":"<your_webhook_id>"
  "name":"<your_webhook_name>",
  "url":"<your_new_webhook_url>",
  "is_enabled":false,
  "secret":"<your_webhook_secret>"
}

Bei einem Webhook mit dem Status „Aktiviert“ für eine Bearbeitung des Webhooks dazu, dass dieser deaktiviert wird. Sie müssen die Verifizierung des Webhooks erfolgreich abschließen, um diesen zu aktivieren.

Eine Liste mit Webhooks erhalten

Stellen Sie die folgende GET-Anfrage, um eine Liste mit all Ihren Webhooks zu erhalten:

curl -X GET \
  -H 'X-API-KEY:<your_api_key>' \
  -H "Content-type:application/json" \
'https://<your_company>.manage.iotium.io/api/v2/webhook/'

Die Antwort beinhaltet Details all Ihrer Webhooks, einschließlich Name, ID, URL, Status und Anzahl an Meldungen, die zur Benachrichtigung genutzt werden:

[
  {
  "id":"<your_webhook_1_id>",
  "name":<your_webhook_1_name>",
  "url":"<your_webhook_1_url>",
  "metadata":{"labels":{"key":"value"}},
  "headers":{"key", "value"},
  "is_enabled":true,
  "created_at":"2020-02-26T08:18:58.022Z",
  "created_by":{"id":"<your_user_id>", "name":"<your_user_name>"},
  "subscription_count":2
  }
  {
  "id":"<your_webhook_2_id>",
  "name":<your_webhook_2_name>",
  "url":"<your_webhook_2_url>",
  "metadata":{"labels":{"key":"value"}},
  "headers":{"key", "value"},
  "is_enabled":true,
  "created_at":"2020-02-27T09:28:59.022Z",
  "created_by":{"id":"<your_user_id>", "name":"<your_user_name>"},
  "subscription_count":1
  }
]

Stellen Sie die folgende GET-Anfrage, um die Details eines bestimmten Webhooks zu erhalten:

curl -X GET \
  -H 'X-API-KEY:<your_api_key>' \
  -H "Content-type:application/json" \
'https://<your_company>.manage.iotium.io/api/v1/webhook/<your_webhook_id>'

Die Antwort beinhaltet Details dieses Webhooks, einschließlich Name, ID, URL, Status und Anzahl an Meldungen:

{
  "id":"<your_webhook_id>",
  "name":"<your_webhook_name>",
  "url":"<your_webhook_url>",
  "metadata":{"labels":{"key":"value"}},
  "headers":{"key", "value"},
  "is_enabled":true,
  "created_at":"2020-02-26T08:18:58.022Z",
  "created_by":{"id":"<your_user_id>", "name":"<your_user_name>"},
  "subscription_count":2
}

Webhooks testen

Sie können eine Beispielbenachrichtigung erstellen, um Ihren Webhook zu testen. Stellen Sie die folgende POST-Anfrage mit den Parametern des Anfrage-Bodys:

curl -X POST \
  -H 'X-API-KEY:<your_api_key>' \
  -H "Content-type:application/json" \
  -d '{"alert_type":"<your_alert_notification_type>"}' \
'https://<your_company>.manage.iotium.io/api/v1/webhook/<your_webhook_id>/test'

Bei einem deaktivierten Webhook werden wir mit dem Statuscode 422 (Unprocessable Entity) antworten. Andernfalls stellen wir eine POST-Anfrage an Ihren Webhook-Endpunkt mit einer Beispielbenachrichtigung mit JSON-Body, basierend auf dem festgelegten Meldungstyp der Benachrichtigung.

Sie erhalten nach fünf Sekunden eine Antwort von Ihrem Webhook-Endpunkt. Sollte die Anfrage ablaufen oder fehlschlagen, werden wir es nicht erneut versuchen. Im Erfolgsfall schicken wir die Antwort von Ihrem Webhook-Endpunkt zurück:

{
  "status":<your_webhook_response_status>,
  "response":"<your_webhook_response_body>"
 }

Webhooks entfernen

Standardmäßig können Sie einen Webhook nicht entfernen, falls dieser genutzt wird, um Meldungen zu verschicken. Falls Sie den Webhook dennoch entfernen möchten, müssen Sie die Option Erzwingen nutzen.

Um das Entfernen eines Webhooks zu erzwingen, der nicht für Meldungen genutzt wird, stellen Sie die folgende DELETE-Anfrage:

curl -X DELETE \
  -H 'X-API-KEY:<your_api_key>' \
  -H "Content-type:application/json" \
'https://<your_company>.manage.iotium.io/api/v1/user/webhook/<your_webhook_id>'

Um das Entfernen eines Webhooks zu erzwingen, der für Meldungen genutzt wird, stellen Sie die folgende DELETE-Anfrage:

curl -X DELETE \
  -H 'X-API-KEY:<your_api_key>' \
  -H "Content-type:application/json" \
'https://<your_company>.manage.iotium.io/api/v1/user/webhook/<your_webhook_id>?force=true'

Status von Webhooks verstehen

Um die Status von Webhooks zu verstehen, müssen Sie Folgendes beachten:

• Wenn Sie einen neuen Webhook hinzufügen, ist dessen Status „Deaktiviert“.
• Bei einer erfolgreichen Verifizierung eines Webhooks ändert sich dessen Status zu „Aktiviert“ und er kann genutzt werden.
• Bei einer Aktualisierung oder Bearbeitung eines Webhooks ist dessen Status „Deaktiviert“.
• Falls eine Benachrichtigungsanforderung eines Webhooks 10-mal fehlschlägt, ändert sich sein Status zu „Deaktiviert“. In diesem Fall müssen Sie die Verifizierung des Webhooks wiederholen, um diesen zu aktivieren.

In dem folgenden Schaubild sind die verschiedenen Status dargestellt: