Benachrichtigungen mit Webhooks einrichten

Sie sehen die Dokumentation zu Apigee Edge.
Zur Apigee X-Dokumentation weitere Informationen

Was ist ein Webhook?

Ein Webhook definiert einen HTTP-Callback-Handler, der durch ein Ereignis ausgelöst wird. Alternativ kannst du Webhooks erstellen und für die Verarbeitung von Ereignisbenachrichtigungen konfigurieren. Eine Alternative zu den Benachrichtigungsvorlagen für die Monetarisierung sind unter Benachrichtigungen mithilfe von Benachrichtigungsvorlagen einrichten beschrieben.

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 die 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 Tarif über die UI oder API ein.

Webhooks verwalten

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

Webhooks über die UI verwalten

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

• Seite „Webhooks“
• Webhook über die UI hinzufügen
• Webhook über die UI bearbeiten
• Webhook über die UI löschen

Seite „Webhooks“ kennenlernen

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

Webhook über die UI hinzufügen

So fügen Sie einen Webhook über die UI hinzu:

1. Rufen Sie die Seite Webhooks auf.
2. Klicken Sie auf + Webhook.
3. Geben Sie die folgenden Informationen ein (alle Felder sind erforderlich).
   

   Feld	Beschreibung
   Name	Name des Webhooks.
   URL	URL des Callback-Handlers, der beim Auslösen der Ereignisbenachrichtigung aufgerufen wird. Siehe 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 UI:

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 UI:

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 UI 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 mithilfe der API verwalten

Sie können Webhooks mithilfe der API hinzufügen und verwalten, wie in den folgenden Abschnitten beschrieben.

• Alle Webhooks mithilfe der API ansehen
• Webhook mit der API ansehen
• Webhook mithilfe der API hinzufügen
• Webhook mit der API bearbeiten
• Webhook mit der API löschen

Alle Webhooks mithilfe der API ansehen

Sehen Sie sich alle Webhooks an, 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

Sie können sich einen einzelnen Webhook ansehen, 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 mit der API hinzufügen

Fügen Sie einen Webhook hinzu, indem Sie eine POST-Anfrage an /mint/organizations/{org_name}/webhooks senden. Du musst 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 dem Webhook 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 POST-Anfrage an /mint/organizations/{org_name}/webhooks/{webhook_id}. Übergeben Sie die Updates im Text der Anfrage.

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

curl -X POST "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 mithilfe der API aktivieren oder deaktivieren

Sie können einen Webhook aktivieren oder deaktivieren, 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.

Durch folgende Aktion wird beispielsweise webhook3 aktiviert:

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}.

Legen Sie den Abfrageparameter forceDelete auf true oder false fest, um anzugeben, ob das Löschen des Webhooks erzwungen werden soll, wenn Prozesse ausgeführt werden. Der Abfrageparameter forceDelete ist standardmäßig aktiviert (true).

So wird beispielsweise 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. Der Callback-Handler muss die Anfrage ordnungsgemäß verarbeiten.

{
        "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 Tarif mit anpassbarem Tarif einrichten

Richten Sie Benachrichtigungen mithilfe von Webhooks für einen Tarif mit anpassbarem Tarif über die UI oder API ein.

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

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

Auf das Dialogfeld „Benachrichtigungen“ für einen Tarif mit anpassbarem Tarif zugreifen

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

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

So fügen Sie der Benutzeroberfläche Benachrichtigungen für einen anpassbaren Tarif hinzu:

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

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

3. Wenn Sie weitere Benachrichtigungsbedingungen festlegen möchten, klicken Sie 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 einen anpassbaren Tarifplan mithilfe der Benutzeroberfläche bearbeiten

So bearbeiten Sie Benachrichtigungen für einen anpassbaren Tarifplan auf der Benutzeroberfläche:

1. Öffnen Sie das Dialogfeld „Benachrichtigungen“.
2. Klicken Sie in der Spalte „Aktionen“ des Preisplans 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 Plan mit anpassbarem Tarif ü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“ des Preisplans auf +Benachrichtigen.
3. Klicken Sie auf Benachrichtigung löschen.

Benachrichtigungen für einen Tarif mit anpassbarem Tarif mithilfe der API einrichten

Wenn Sie eine Benachrichtigung für einen Tarif mit anpassbarem Tarif mithilfe der API einrichten möchten, folgen Sie der unter Benachrichtigungsbedingungen und Aktionen mit der API verwalten beschriebenen Vorgehensweise und verwenden Sie die in diesem Abschnitt beschriebenen Attribute.

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

Attribut	Wert
RATEPLAN	ID des anpassbaren Plans für die Benachrichtigungsrate.
PUBLISHED	TRUE gibt an, dass der anpassbare Tarif für die Benachrichtigungen veröffentlicht werden muss.
UsageTarget	Prozentsatz der Zielanzahl von Transaktionen, zu der eine Benachrichtigung ausgelöst werden soll. Mit diesem Attribut können Sie Entwickler benachrichtigen, wenn sie sich der Zielanzahl von Transaktionen für eine von ihnen erworbene anpassbare Benachrichtigungspreisliste nähern oder diese erreicht haben. Wenn ein Entwickler beispielsweise einen Tarif mit anpassbarer Benachrichtigungsrate erworben hat und die Zielanzahl von Transaktionen für den Entwickler auf 1.000 festgelegt wurde, können Sie 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. Beispielsweise sendet %= 80 Benachrichtigungen, wenn der Prozentsatz der Zielanzahl von Transaktionen 80 % erreicht. Wenn Sie einen Prozentbereich festlegen möchten, geben Sie den Anfangs- und Endprozentsatz sowie den gewünschten Wert für die Erhöhung ein: %= start to end by n. Beispielsweise werden durch den Wert %= 80 to 100 by 10 Benachrichtigungen gesendet, wenn der Prozentsatz der Zielanzahl von Transaktionen 80%, 90 % und 100 % erreicht.

Legen Sie unter actions die folgenden Werte fest, um die Benachrichtigungsaktion einzurichten. Weitere Informationen finden Sie unter Konfigurationsattribute für Benachrichtigungsaktionen.

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

Das folgende Beispiel zeigt, wie Sie eine Benachrichtigungsbedingung erstellen, die einen Webhook auslöst, wenn der Prozentsatz der Zielanzahl 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 Anzeigen, Aktualisieren und Löschen einer Benachrichtigungsbedingung und -aktion findest du unter:

• Benachrichtigungsbedingung und Aktion mit der API ansehen
• Benachrichtigungsbedingung und Aktion mithilfe der API bearbeiten
• Benachrichtigungsbedingung und Aktion mit der API löschen

Webhook-Antwortcodes

Im Folgenden finden Sie eine Übersicht über die Webhook-Antwortcodes und wie sie vom System interpretiert werden.

Antwortcode	Beschreibung
2xx	Abgeschlossen
5xx	Anfrage fehlgeschlagen. Das System wiederholt die Anfrage bis zu dreimal in 5-Minuten-Intervallen. Hinweis: Die Zeitüberschreitungen für Lese- und Verbindungsherstellung bei Webhook-Anfragen betragen jeweils 3 Sekunden. Dies kann zu fehlgeschlagenen Anfragen führen.
Other response	Anfrage fehlgeschlagen. Das System wiederholt die Anfrage nicht.