Benachrichtigungen mit Webhooks einrichten

Sie sehen sich die Dokumentation zu Apigee Edge an.
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 zu den Benachrichtigungsvorlagen für die Monetarisierung können Sie Webhooks erstellen und für die Verarbeitung von Ereignisbenachrichtigungen konfigurieren. Eine Beschreibung hierzu finden Sie unter Benachrichtigungen mithilfe von Benachrichtigungsvorlagen einrichten.

So richtest du Benachrichtigungen mit Webhooks ein: Führe die folgenden Schritte über die Edge Management-Benutzeroberfläche oder die Management and Monetization API aus:

  1. Fügen Sie Webhooks hinzu, die die Rückruf-Handler für die Benachrichtigungsereignisse definieren. Verwenden Sie dazu die Benutzeroberfläche oder die API.
  2. Richten Sie den Callback-Handler ein.
  3. Richten Sie die Benachrichtigung für ein anpassbares Tarifpaket über die Benutzeroberfläche oder die API ein.

Webhooks verwalten

Fügen Sie Webhooks hinzu und verwalten Sie sie, um die Callback-Handler für die Benachrichtigungsereignisse mithilfe der Benutzeroberfläche oder der API zu definieren.

Webhooks über die Benutzeroberfläche verwalten

Fügen Sie Webhooks hinzu und verwalten Sie sie, die die Rückruf-Handler für die Benachrichtigungsereignisse über die Benutzeroberfläche definieren, wie in den folgenden Abschnitten beschrieben.

Die Seite „Webhooks“

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

Edge

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

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

Die Seite „Webhooks“ wird angezeigt.

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

Klassisches Edge (Private Cloud)

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

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

  2. Wählen Sie Verwaltung > Webhooks aus.

Die Seite „Webhooks“ wird angezeigt.

Auf der Seite „Webhooks“ haben Sie folgende Möglichkeiten:

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 Pflichtfelder).
    Feld Beschreibung
    Name Name des Webhooks.
    URL URL des Rückruf-Handlers, der aufgerufen wird, wenn die Ereignisbenachrichtigung ausgelöst wird. Weitere Informationen finden Sie unter Callback-Handler einrichten.
  4. Klicken Sie 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).

Webhooks ü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 klicken Sie auf den Statusschalter, um ihn zu aktivieren oder zu deaktivieren.

Webhook über die Benutzeroberfläche löschen

So löschen Sie einen Webhook über die Benutzeroberfläche:

  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

Alle Webhooks ansehen, indem Sie eine GET-Anfrage an /mint/organizations/{org_name}/webhooks senden 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 mit der API ansehen

Wenn Sie einen einzelnen Webhook aufrufen möchten, senden Sie eine GET-Anfrage an /mint/organizations/{org_name}/webhooks/{webhook_id}.

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 senden. Sie müssen den Namen des Webhooks und die URL des Callback-Handlers übergeben, der beim Auslösen der Ereignisbenachrichtigung aufgerufen wird.

Mit dem folgenden Beispiel wird beispielsweise 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 mit der API bearbeiten

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

Im folgenden Beispiel wird beispielsweise der mit webhook1 verknüpfte Rückruf-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"
}

Webhooks mit der 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 nicht ausgelöst, wenn ein Ereignis eintritt.

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 mit der API löschen

Senden Sie eine DELETE-Anfrage an /mint/organizations/{org_name}/webhooks/{webhook_id}, um einen Webhook zu löschen.

Wenn Sie angeben möchten, ob der Webhook bei laufenden Prozessen gelöscht werden soll, setzen Sie den Abfrageparameter forceDelete auf true oder false. Der forceDelete-Abfrageparameter 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 vom Webhook definierten Rückruf-Handler gesendet wird, wenn eine Ereignisbenachrichtigung ausgelöst wird. Sie müssen dafür sorgen, dass der Rückruf-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 Tarifplan einrichten

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

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

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

Auf das Dialogfeld „Benachrichtigungen“ für einen anpassbaren Tarifplan zugreifen

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

Edge

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

  1. Erstellen und veröffentlichen Sie einen anpassbaren Benachrichtigungstarifplan, wie unter Details zum anpassbaren Benachrichtigungstarifplan angeben beschrieben.
  2. Wählen Sie in der linken Navigationsleiste Veröffentlichen > Monetarisierung > Tarifpakete aus, um die Seite „Tarifpakete“ aufzurufen.
  3. Bewegen Sie den Mauszeiger auf den veröffentlichten Tarifplan für anpassbare Benachrichtigungen, um Aktionen einzublenden.
  4. Klicken Sie auf +Benachrichtigen.

    Das Dialogfeld „Benachrichtigungen“ wird angezeigt.

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

Klassisches Edge (Private Cloud)

So rufen Sie die Seite „Benachrichtigungen“ auf:

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

    Das Dialogfeld „Benachrichtigungen“ wird angezeigt.

Benachrichtigungen für ein anpassbares Tarifpaket über die Benutzeroberfläche hinzufügen

So fügen Sie über die Benutzeroberfläche Benachrichtigungen für ein anpassbares Tarifpaket hinzu:

  1. Rufen Sie das Dialogfeld „Benachrichtigungen“ auf.
  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:
    • Wenn Sie einen genauen Prozentsatz festlegen möchten, geben Sie ihn in das Feld Bei/Ab % ein und lassen Sie das Feld Bis % leer.
    • Wenn Sie einen Prozentsatzbereich festlegen möchten, geben Sie den Anfangs- und Endprozentsatz in die Felder Bei/Ab % und Zu % ein und einen Schrittwert in das Feld Schritt %. Standardmäßig werden Benachrichtigungen in Schritten von 10 % innerhalb des angegebenen Bereichs gesendet.

    Das Feld Notify At wird aktualisiert, um den Prozentsatz der Zielzahl an Transaktionen widerzuspiegeln, 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, indem Sie einen oder mehrere Webhooks auswählen, um die Callback-Verarbeitung zu verwalten, wenn Benachrichtigungen ausgelöst werden.
  5. Klicken Sie auf Benachrichtigung erstellen.

Benachrichtigungen für ein anpassbares Tarifpaket über die Benutzeroberfläche bearbeiten

So bearbeiten Sie Benachrichtigungen für ein anpassbares Tarifpaket über die Benutzeroberfläche:

  1. Rufen Sie das Dialogfeld „Benachrichtigungen“ auf.
  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. Rufen Sie das Dialogfeld „Benachrichtigungen“ auf.
  2. Klicken Sie in der Spalte „Aktionen“ für den Preisplan auf + Benachrichtigen.
  3. Klicken Sie auf Benachrichtigung löschen.

Benachrichtigungen für ein anpassbares Tarifpaket mithilfe der API einrichten

Wenn Sie eine Benachrichtigung für ein anpassbares Tarifpaket mithilfe der API einrichten möchten, folgen Sie der Anleitung unter Benachrichtigungsbedingungen und ‑aktionen mithilfe der API verwalten und verwenden Sie die in diesem Abschnitt beschriebenen Attribute.

Verwenden Sie die folgenden Attributwerte, um die Benachrichtigungsbedingung (notificationCondition) einzurichten. Weitere Informationen finden Sie unter Konfigurationsattribute für Benachrichtigungsbedingungen.

Attribut Wert
RATEPLAN ID des anpassbaren Benachrichtigungstarifs.
PUBLISHED TRUE, um anzugeben, dass das Tarifpaket für anpassbare 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 die Zielanzahl von Transaktionen für einen gekauften Kartentarif mit anpassbarer Benachrichtigungsrate erreichen oder diese überschreiten. Wenn ein Entwickler beispielsweise einen anpassbaren Benachrichtigungstarif erworben hat und die Zielanzahl der Transaktionen für den Entwickler auf 1.000 festgelegt wurde, können Sie ihn benachrichtigen, wenn er 800 Transaktionen (80% der Zielanzahl der Transaktionen), 1.000 Transaktionen (100%) oder 1.500 Transaktionen (150%) erreicht hat.

  • Wenn Sie einen genauen Prozentsatz festlegen möchten, geben Sie %= n ein. %= 80 sendet beispielsweise Benachrichtigungen, wenn der Prozentsatz der Zielzahl an Transaktionen 80 % erreicht.
  • Wenn Sie einen Prozentsatzbereich festlegen möchten, geben Sie den Start- und Endprozentsatz sowie den Wert ein, um den der Prozentsatz erhöht werden 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.

Legen Sie unter actions die folgenden Werte fest, um die Benachrichtigungsaktion einzurichten. 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 mit der API erstellen definiert haben.

Im Folgenden finden Sie ein Beispiel für die Erstellung einer Benachrichtigungsbedingung, die einen Webhook auslöst, wenn der Prozentsatz der Zielzahl an 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 Ansehen, Aktualisieren und Löschen einer Benachrichtigungsbedingung und ‑aktion finden Sie unter:

Webhook-Antwortcodes

Im Folgenden werden die Webhook-Antwortcodes und ihre Interpretation durch das System zusammengefasst.

Antwortcode Beschreibung
2xx Erfolg
5xx

Anfrage fehlgeschlagen. Das System versucht, die Anfrage bis zu dreimal in 5-Minuten-Intervallen noch einmal zu senden.

Hinweis : Die Lese- und Verbindungszeiten für Webhook-Anfragen betragen jeweils 3 Sekunden. Das kann zu fehlgeschlagenen Anfragen führen.
Other response Anfrage fehlgeschlagen. Das System versucht nicht noch einmal, die Anfrage zu senden.