Benachrichtigungen mit Webhooks einrichten

Sie lesen die Dokumentation zu Apigee Edge.
Rufen Sie die Dokumentation zu Apigee X auf. Weitere Informationen

Was ist ein Webhook?

Ein Webhook definiert einen HTTP-Callback-Handler, der durch ein Ereignis ausgelöst wird. Als Alternative zur Verwendung der Vorlagen für Monetarisierungsbenachrichtigungen können Sie Webhooks erstellen und für die Verarbeitung von Ereignisbenachrichtigungen konfigurieren. Eine Beschreibung hierzu finden Sie unter Benachrichtigungen mithilfe von Benachrichtigungsvorlagen einrichten.

Führen Sie zum Einrichten von Benachrichtigungen mithilfe von Webhooks die folgenden Schritte über die Edge Management-Benutzeroberfläche oder die Management and Monetization API aus:

  1. Füge über die UI oder API Webhooks hinzu, die die Callback-Handler für die Benachrichtigungsereignisse definieren.
  2. Richten Sie den Callback-Handler ein.
  3. Richten Sie die Benachrichtigung für einen anpassbaren Preisplan über die UI oder API ein.

Webhooks verwalten

Über die UI oder die API kannst du Webhooks hinzufügen und verwalten, die die Callback-Handler für die Benachrichtigungsereignisse definieren.

Webhooks über die Benutzeroberfläche verwalten

Fügen Sie über die Benutzeroberfläche Webhooks hinzu und verwalten Sie sie, um die Callback-Handler für die Benachrichtigungsereignisse zu definieren. Dies wird in den folgenden Abschnitten beschrieben.

Die Seite „Webhooks“ kennenlernen

Rufen Sie die Seite „Webhooks“ wie unten beschrieben auf.

Edge

So greifen Sie über die Edge-Benutzeroberfläche auf die Webhooks-Seite zu:

  1. Melden Sie sich bei apigee.com/edge an.
  2. Wählen Sie in der linken Navigationsleiste Publish > Monetization > Webhooks (Veröffentlichen > Monetarisierung > Webhooks) aus.

Die Seite „Webhooks“ wird angezeigt.

Wie in der Abbildung hervorgehoben, können Sie auf der Seite „Webhooks“ Folgendes tun:

Classic Edge (Private Cloud)

So greifen Sie über die Classic Edge-Benutzeroberfläche auf die Webhooks-Seite zu:

  1. Melden Sie sich bei http://ms-ip:9000 an, wobei ms-ip die IP-Adresse oder der DNS-Name des Knotens des Verwaltungsservers ist.

  2. Wählen Sie Admin > Webhooks aus.

Die Seite „Webhooks“ wird angezeigt.

Auf der Seite „Webhooks“ können Sie:

Webhook über die Benutzeroberfläche hinzufügen

So fügen Sie einen Webhook über die Benutzeroberfläche hinzu:

  1. Rufen Sie die Seite Webhooks auf.
  2. Klicken Sie auf + Webhook.
  3. Geben Sie die folgenden Informationen ein (alle Felder sind erforderlich).
    Field Beschreibung
    Name Name des Webhooks.
    URL URL des Callback-Handlers, der aufgerufen wird, wenn die Ereignisbenachrichtigung ausgelöst wird. Siehe Callback-Handler einrichten.
  4. Klicke auf Speichern.

Der Webhook wird der Liste hinzugefügt und standardmäßig aktiviert.

Webhook über die Benutzeroberfläche bearbeiten

So bearbeiten Sie einen Webhook über die Benutzeroberfläche:

  1. Rufen Sie die Seite Webhooks auf.
  2. Bewegen Sie den Mauszeiger auf den Webhook, den Sie bearbeiten möchten, und klicken Sie im Aktionsmenü auf .
  3. Bearbeiten Sie die Webhook-Felder nach Bedarf.
  4. Klicken Sie auf Update Webhook (Webhook aktualisieren).

Webhook über die Benutzeroberfläche aktivieren oder deaktivieren

So aktivieren oder deaktivieren Sie einen Webhook über die Benutzeroberfläche:

  1. Rufen Sie die Seite Webhooks auf.
  2. Bewegen Sie den Mauszeiger auf den Webhook und bewegen Sie den Statusschalter, um ihn zu aktivieren oder zu deaktivieren.

Webhook über die Benutzeroberfläche löschen

So löschen Sie einen Webhook über die UI:

  1. Rufen Sie die Seite Webhooks auf.
  2. Bewegen Sie den Mauszeiger auf den Webhook, den Sie löschen möchten, und klicken Sie auf .

Der Webhook wird gelöscht und aus der Liste entfernt.

Webhooks mit der API verwalten

Fügen Sie Webhooks mithilfe der API hinzu und verwalten Sie sie, wie in den folgenden Abschnitten beschrieben.

Alle Webhooks mithilfe der API aufrufen

Wenn Sie alle Webhooks aufrufen möchten, senden Sie eine GET-Anfrage an /mint/organizations/{org_name}/webhooks. Beispiel:

curl -X GET "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks" \
  -H "Content-Type: application/json " \
  -u email:password

Im Folgenden finden Sie ein Beispiel für die zurückgegebene Antwort:

{
  "totalRecords": 2,
  "webhooks": [
    {
      "created": 1460162656342,
      "enabled": false,
      "id": "21844a37-d26d-476c-93ed-38f3a4b24691",
      "name": "webhook1",
      "postUrl": "http://mycompany.com/callbackhandler1",
      "updated": 1460162656342,
      "updatedBy": "joe@example.com"
    },
        {
      "created": 1460138724352,
      "createdBy": "joe@example.com",
      "enabled": true,
      "id": "a39ca777-1861-49cf-a397-c9e92ab3c09f",
      "name": "webhook2",
      "postUrl": "http://mycompany.com/callbackhandler2",
      "updated": 1460138724352,
      "updatedBy": "joe@example.com"
    }

  ]
}

Webhook mithilfe der API aufrufen

Sie können einen einzelnen Webhook aufrufen, indem Sie eine GET-Anfrage an /mint/organizations/{org_name}/webhooks/{webhook_id} senden.

Beispiel:

curl -X GET "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks/21844a37-d26d-476c-93ed-38f3a4b24691" \
  -H "Content-Type: application/json " \
  -u email:password

Im Folgenden finden Sie ein Beispiel für die Antwort:

{
   "created": 1460162656342,
   "enabled": false,
   "id": "21844a37-d26d-476c-93ed-38f3a4b24691",
   "name": "webhook1",
   "postUrl": "http://mycompany.com/callbackhandler1",
   "updated": 1460162656342,
   "updatedBy": "joe@example.com"
 }

Webhook mithilfe der API hinzufügen

Fügen Sie einen Webhook hinzu, indem Sie eine POST-Anfrage an /mint/organizations/{org_name}/webhooks ausgeben. Sie müssen den Namen des Webhooks und die URL des Callback-Handlers übergeben, der beim Auslösen der Ereignisbenachrichtigung aufgerufen wird.

Im folgenden Beispiel wird ein Webhook mit dem Namen webhook3 erstellt und ihm callbackhandler3 zugewiesen:

curl -X POST "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks"
  -H "Content-Type: application/json "
  -d '{
    "name": "webhook3",
    "postURL": "http://mycompany.com/callbackhandler3"
    }' \
    -u email:password

Im Folgenden finden Sie ein Beispiel für die Antwort:

{
  "created": 1460385534555,
  "createdBy": "joe@example.com",
  "enabled": false,
  "id": "0a07eb1f-f485-4539-8beb-01be449699b3",
  "name": "webhook3",
  "orgId": "myorg",
  "postUrl": "http://mycompany.com/callbackhandler3",
  "updated": 1460385534555,
  "updatedBy": "joe@example.com"
}

Webhook mithilfe der API bearbeiten

Zum Bearbeiten eines Webhooks senden Sie eine PUT-Anfrage an /mint/organizations/{org_name}/webhooks/{webhook_id}. Übergeben Sie die Aktualisierungen im Text der Anfrage.

Im folgenden Beispiel wird der mit webhook1 verknüpfte Callback-Handler aktualisiert:

curl -X PUT "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks/0a07eb1f-f485-4539-8beb-01be449699b3" \
  -H "Content-Type: application/json " \
  -d '{
    "postURL": "http://mycompany.com/callbackhandler4"
  }' \
  -u email:password

Im Folgenden finden Sie ein Beispiel für die Antwort:

{
  "created": 1460385534555,
  "enabled": false,
  "id": "0a07eb1f-f485-4539-8beb-01be449699b3",
  "name": "webhook3",
  "orgId": "myorg",
  "postUrl": "http://mycompany.com/callbackhandler4",
  "updated": 1460385534555,
  "updatedBy": "joe@example.com"
}

Webhook über die API aktivieren oder deaktivieren

Aktivieren oder deaktivieren Sie einen Webhook, indem Sie eine POST-Anfrage an /mint/organizations/{org_name}/webhooks/{webhook_id} senden, wie Sie es beim Aktualisieren eines Webhooks getan haben, und das aktivierte Attribut im Anfragetext auf „true“ oder „false“ setzen. Wenn Sie den Webhook deaktivieren, wird er beim Eintreten eines Ereignisses nicht ausgelöst.

Das folgende Beispiel aktiviert webhook3:

curl -X POST "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks/0a07eb1f-f485-4539-8beb-01be449699b3" \
  -H "Content-Type: application/json " \
  -d '{
    "enabled": "true"
  }' \
  -u email:password

Im Folgenden finden Sie ein Beispiel für die Antwort:

{
  "created": 1460385534555,
  "enabled": true,
  "id": "0a07eb1f-f485-4539-8beb-01be449699b3",
  "name": "webhook3",
  "orgId": "myorg",
  "postUrl": "http://mycompany.com/callbackhandler4",
  "updated": 1460385534555,
  "updatedBy": "joe@example.com"
}

Webhook mithilfe der API löschen

Zum Löschen eines Webhooks senden Sie eine DELETE-Anfrage an /mint/organizations/{org_name}/webhooks/{webhook_id}.

Wenn Sie angeben möchten, ob das Löschen des Webhooks erzwungen werden soll, wenn Prozesse aktiv sind, setzen Sie den Abfrageparameter forceDelete auf true oder false. Der Abfrageparameter forceDelete ist standardmäßig aktiviert (true).

Beispielsweise wird webhook3 gelöscht:

curl -X DELETE "https://api.enterprise.apigee.com/v1/mint/organizations/myorg/webhooks/21844a37-d26d-476c-93ed-38f3a4b24691" \
  -H "Content-Type: application/json " \
  -u email:password

Callback-Handler einrichten

Im Folgenden sehen Sie das Format der JSON-Anfrage, die an den von einem Webhook definierten Callback-Handler gesendet wird, wenn eine Ereignisbenachrichtigung ausgelöst wird. Sie müssen dafür sorgen, dass der Callback-Handler die Anfrage ordnungsgemäß verarbeitet.

{
        "orgName": "{org_id}",
        "developerEmail": "{dev_email}",
        "developerFirstName": "{first_name}",
        "developerLastName": "{last_name}",
        "companyName": "{company_name}",
        "applicationName": "{app_name}",
        "packageName": "{api_package_name}",
        "packageId": "{api_package_id}",
        "ratePlanId": "{rateplan_id}",
        "ratePlanName": "{rateplan_name}",
        "ratePlanType": "{rateplan_type}",
        "developerRatePlanQuotaTarget": {quota_target},
        "quotaPercentUsed": {percentage_quota_used},
        "ratePlanStartDate": {rateplan_startdate}, 
        "ratePlanEndDate": {rateplan_enddate},
        "nextBillingCycleStartDate": {next_billing_cycle_startdate},
        "products": ["{api_product_name}","{api_product_name}"],
        "developerCustomAttributes": [],
        "triggerTime": {trigger_time},
        "triggerReason": "{trigger_reason}",
        "developerQuotaResetDate": "{devquota_resetdate}"
}

Benachrichtigungen für einen anpassbaren Preisplan einrichten

Richten Sie Benachrichtigungen mithilfe von Webhooks für einen anpassbaren Preisplan über die Benutzeroberfläche oder API ein.

Benachrichtigungen für einen anpassbaren Preisplan über die Benutzeroberfläche einrichten

Richten Sie Benachrichtigungen mithilfe von Webhooks für einen anpassbaren Preisplan über die Benutzeroberfläche ein, wie unten beschrieben.

Rufen Sie das Dialogfeld „Benachrichtigungen“ auf, um einen anpassbaren Tarifplan zu erhalten

Rufen Sie das Dialogfeld „Benachrichtigungen“ für einen anpassbaren Preisplan auf, wie unten beschrieben.

Edge

So greifen Sie über die Edge-Benutzeroberfläche auf das Benachrichtigungsdialogfeld zu:

  1. Erstellen und veröffentlichen Sie einen anpassbaren Tarif für Benachrichtigungen, wie unter Details zu anpassbaren Benachrichtigungsplänen angeben beschrieben.
  2. Rufen Sie die Seite „Preispläne“ auf, indem Sie in der linken Navigationsleiste Veröffentlichen > Monetarisierung > Preispläne auswählen.
  3. Bewegen Sie den Mauszeiger über den veröffentlichten Tarif für anpassbare Benachrichtigungen, um Aktionen anzuzeigen.
  4. Klicken Sie auf +Benachrichtigen.

    Das Dialogfeld „Benachrichtigungen“ wird angezeigt.

    Hinweis: Der Preisplan muss veröffentlicht sein, damit die Aktion „+Benachrichtigen“ angezeigt wird.

Classic Edge (Private Cloud)

So greifen Sie auf die Seite „Benachrichtigungen“ zu:

  1. Erstellen Sie einen anpassbaren Tarif für Benachrichtigungen, wie unter Details zum anpassbaren Benachrichtigungsplan angeben beschrieben.
  2. Wählen Sie Veröffentlichen > Pakete aus, um die Preispläne aufzurufen.
  3. Klicken Sie in der Spalte „Aktionen“ für den Preisplan auf +Benachrichtigen.

    Das Dialogfeld „Benachrichtigungen“ wird angezeigt.

Benachrichtigungen für einen anpassbaren Preisplan über die Benutzeroberfläche hinzufügen

So fügen Sie Benachrichtigungen für einen anpassbaren Preisplan über die Benutzeroberfläche hinzu:

  1. Öffnen Sie das Dialogfeld "Benachrichtigungen".
  2. Legen Sie die Benachrichtigungsbedingung unter Benachrichtigungsintervalle fest. Geben Sie dazu einen Prozentsatz der angestrebten Anzahl von Transaktionen an, zu der eine Benachrichtigung ausgelöst werden soll. Im Detail:
    • Um einen genauen Prozentsatz festzulegen, geben Sie diesen in das Feld Um/Ab % ein und lassen Sie das Feld Bis % leer.
    • Um einen Prozentbereich festzulegen, geben Sie den Start- und Endprozentsatz in die Felder At/From % und Bis % und einen schrittweisen Wert in das Feld Schritt % ein. Standardmäßig werden Benachrichtigungen in Schritten von 10 % innerhalb des angegebenen Bereichs gesendet.

    Das Feld Notify At wird aktualisiert, um jeden Prozentsatz der angestrebten Anzahl von Transaktionen anzugeben, die ein Ereignis auslösen.

  3. Klicken Sie zum Festlegen weiterer Benachrichtigungsbedingungen auf + Hinzufügen und wiederholen Sie Schritt 4.
  4. Legen Sie die Benachrichtigungsaktion unter Webhooks fest. Wählen Sie dazu einen oder mehrere Webhooks aus, um die Callback-Verarbeitung beim Auslösen von Benachrichtigungen zu verwalten.
  5. Klicken Sie auf Benachrichtigung erstellen.

Benachrichtigungen für einen anpassbaren Preisplan über die Benutzeroberfläche bearbeiten

So bearbeiten Sie Benachrichtigungen für einen anpassbaren Preisplan in der Benutzeroberfläche:

  1. Öffnen Sie das Dialogfeld "Benachrichtigungen".
  2. Klicken Sie in der Spalte „Aktionen“ für den Preisplan auf +Benachrichtigen.
  3. Klicken Sie auf Bearbeiten.
  4. Ändern Sie die Werte nach Bedarf.
  5. Klicken Sie auf Benachrichtigung speichern.

Löschen von Benachrichtigungen für einen anpassbaren Preisplan über die Benutzeroberfläche

So löschen Sie eine Benachrichtigungsbedingung und -aktion:

  1. Öffnen Sie das Dialogfeld "Benachrichtigungen".
  2. Klicken Sie in der Spalte „Aktionen“ für den Preisplan auf +Benachrichtigen.
  3. Klicken Sie auf Benachrichtigung löschen.

Benachrichtigungen für einen anpassbaren Preisplan mithilfe der API einrichten

Wenn Sie mithilfe der API eine Benachrichtigung für einen anpassbaren Preisplan einrichten möchten, gehen Sie wie unter Benachrichtigungsbedingungen und -aktionen über die API verwalten beschrieben vor und verwenden Sie die in diesem Abschnitt beschriebenen Attribute.

Verwenden Sie zum Einrichten der Benachrichtigungsbedingung (notificationCondition) die folgenden Attributwerte. Weitere Informationen finden Sie unter Konfigurationseigenschaften für Benachrichtigungsbedingungen.

Attribut Wert
RATEPLAN ID des anpassbaren Tarifplans für Benachrichtigungen.
PUBLISHED TRUE gibt an, dass der anpassbare Tarif für Benachrichtigungen veröffentlicht werden muss.
UsageTarget Prozentsatz der angestrebten Anzahl von Transaktionen, zu der eine Benachrichtigung ausgelöst werden soll.

Mit diesem Attribut können Sie Entwickler benachrichtigen, wenn sie ihre angestrebte Anzahl von Transaktionen für einen anpassbaren Preislistenplan für Benachrichtigungen, die sie erworben haben, bald erreichen oder erreicht haben. Wenn ein Entwickler beispielsweise einen anpassbaren Tarif für Benachrichtigungen erworben hat und die Zielanzahl der Transaktionen für den Entwickler auf 1.000 festgelegt wurde, kannst du ihn benachrichtigen, wenn er 800 Transaktionen (80% der angestrebten Anzahl von Transaktionen), 1.000 Transaktionen (100%) oder 1.500 Transaktionen (150%) erreicht hat.

  • Um einen genauen Prozentsatz festzulegen, geben Sie %= n ein. %= 80 sendet beispielsweise Benachrichtigungen, wenn der Prozentsatz der angestrebten Anzahl von Transaktionen 80 % erreicht.
  • Um einen Prozentbereich festzulegen, geben Sie die Anfangs- und Endprozentsätze sowie den Wert ein, um den die Erhöhung wie folgt erfolgen soll: %= start to end by n. Mit dem Wert %= 80 to 100 by 10 werden beispielsweise Benachrichtigungen gesendet, wenn der Prozentsatz der angestrebten Anzahl von Transaktionen 80%, 90 % und 100 % erreicht.

Wenn Sie die Benachrichtigungsaktion einrichten möchten, legen Sie unter actions die folgenden Werte fest. Weitere Informationen finden Sie unter Konfigurationseigenschaften für Benachrichtigungsaktionen.

Attribut Wert
actionAttribute WEBHOOK, um einen Webhook auszulösen.
value ID des Webhooks, den Sie im vorherigen Abschnitt Webhooks mithilfe der API erstellen definiert haben.

Im Folgenden finden Sie ein Beispiel für das Erstellen einer Benachrichtigungsbedingung, die einen Webhook auslöst, wenn der Prozentsatz der angestrebten Anzahl von Transaktionen 80%, 90%, 100%, 110 % und 120 % erreicht.

{
    "notificationCondition": [
      {
        "attribute": "RATEPLAN",
        "value": "123456"
      },
      {
        "attribute": "PUBLISHED",
        "value": "TRUE"
      },
      {
        "attribute": "UsageTarget",
        "value": "%= 80 to 120 by 10"
      }
    } 
    ],
   "actions": [{
          "actionAttribute": "WEBHOOK",
          "value": "b0d77596-142e-4606-ae2d-f55c3c6bfebe",
        }]
  }

Informationen zum Aufrufen, Aktualisieren und Löschen einer Benachrichtigungsbedingung und -aktion finden Sie unter:

Webhook-Antwortcodes

Im Folgenden werden die Webhook-Antwortcodes zusammengefasst und wie sie vom System interpretiert werden.

Antwortcode Beschreibung
2xx Abgeschlossen
5xx

Anfrage fehlgeschlagen. Das System wiederholt die Anfrage bis zu dreimal in Intervallen von 5 Minuten.

Hinweis: Die Zeitüberschreitungen für Lese- und Verbindungsanfragen bei Webhook-Anfragen betragen jeweils 3 Sekunden. Dies kann zu fehlgeschlagenen Anfragen führen.
Other response Anfrage fehlgeschlagen. Das System wiederholt die Anfrage nicht.