Configurer des notifications à l'aide de webhooks

Vous consultez la documentation d'Apigee Edge.
Accédez à la documentation sur Apigee X. info

Qu'est-ce qu'un webhook ?

Un webhook définit un gestionnaire de rappel HTTP déclenché par un événement. Vous pouvez créer des webhooks et les configurer pour gérer les notifications d'événements, au lieu d'utiliser les modèles de notifications de monétisation, comme décrit dans la section Configurer des notifications à l'aide de modèles de notification.

Pour configurer des notifications à l'aide de webhooks, procédez comme suit à l'aide de l'interface utilisateur de gestion Edge ou de l'API Management and Monetization:

  1. Ajoutez des webhooks qui définissent les gestionnaires de rappel pour les événements de notification à l'aide de l'UI ou de l'API.
  2. Configurez le gestionnaire de rappel.
  3. Configurez la notification pour un plan tarifaire ajustable à l'aide de l'interface utilisateur ou de l'API.

Gérer les webhooks

Ajoutez et gérez des webhooks qui définissent les gestionnaires de rappel pour les événements de notification à l'aide de l'interface utilisateur ou de l'API.

Gérer les webhooks à l'aide de l'UI

Ajoutez et gérez des webhooks qui définissent les gestionnaires de rappel pour les événements de notification à l'aide de l'UI, comme décrit dans les sections suivantes.

Explorer la page "Webhooks"

Accédez à la page "Webhooks", comme décrit ci-dessous.

Edge

Pour accéder à la page "Webhooks" à l'aide de l'interface utilisateur Edge:

  1. Connectez-vous à apigee.com/edge.
  2. Sélectionnez Publier > Monétisation > Webhooks dans la barre de navigation de gauche.

La page "Webhooks" s'affiche.

Comme le montre la figure, la page "Webhooks" vous permet de:

Edge classique (cloud privé)

Pour accéder à la page "Webhooks" à l'aide de l'interface utilisateur classique de Edge:

  1. Connectez-vous à http://ms-ip:9000, où ms-ip est l'adresse IP ou le nom DNS du nœud de serveur de gestion.

  2. Sélectionnez Admin > Webhooks.

La page "Webhooks" s'affiche.

La page "Webhooks" vous permet d'effectuer les opérations suivantes:

Ajouter un webhook à l'aide de l'UI

Pour ajouter un webhook à l'aide de l'interface utilisateur:

  1. Accédez à la page Webhooks.
  2. Cliquez sur + Webhook.
  3. Saisissez les informations suivantes (tous les champs sont obligatoires).
    Champ Description
    Nom Nom du webhook.
    URL URL du gestionnaire de rappel qui sera appelé lorsque la notification d'événement sera déclenchée. Consultez Configurer le gestionnaire de rappel.
  4. Cliquez sur Enregistrer.

Le webhook est ajouté à la liste et activé par défaut.

Modifier un webhook à l'aide de l'UI

Pour modifier un webhook à l'aide de l'interface utilisateur:

  1. Accédez à la page Webhooks.
  2. Placez le curseur sur le webhook que vous souhaitez modifier, puis cliquez sur dans le menu d'actions.
  3. Modifiez les champs du webhook si nécessaire.
  4. Cliquez sur Mettre à jour le webhook.

Activer ou désactiver un webhook à l'aide de l'UI

Pour activer ou désactiver un webhook à l'aide de l'UI:

  1. Accédez à la page Webhooks.
  2. Placez le curseur sur le webhook, puis activez ou désactivez-le en appuyant sur le bouton d'état.

Supprimer un webhook à l'aide de l'UI

Pour supprimer un webhook à l'aide de l'UI:

  1. Accédez à la page Webhooks.
  2. Placez le curseur sur le webhook que vous souhaitez supprimer, puis cliquez sur .

Le webhook est supprimé et retiré de la liste.

Gérer les webhooks à l'aide de l'API

Ajoutez et gérez des webhooks à l'aide de l'API, comme décrit dans les sections suivantes.

Afficher tous les webhooks à l'aide de l'API

Affichez tous les webhooks en envoyant une requête GET à /mint/organizations/{org_name}/webhooks. Exemple :

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

Voici un exemple de réponse renvoyée:

{
  "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"
    }

  ]
}

Afficher un webhook à l'aide de l'API

Affichez un seul webhook en envoyant une requête GET à /mint/organizations/{org_name}/webhooks/{webhook_id}.

Exemple :

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

Voici un exemple de réponse :

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

Ajouter un webhook à l'aide de l'API

Ajoutez un webhook en envoyant une requête POST à /mint/organizations/{org_name}/webhooks. Vous devez transmettre le nom du webhook et l'URL du gestionnaire de rappel qui sera appelé lorsque la notification d'événement est déclenchée.

L'exemple suivant crée un webhook nommé webhook3 et attribue callbackhandler3 au webhook:

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

Voici un exemple de réponse :

{
  "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"
}

Modifier un webhook à l'aide de l'API

Modifiez un webhook en envoyant une requête PUT à /mint/organizations/{org_name}/webhooks/{webhook_id}. Transmettez les mises à jour dans le corps de la requête.

Par exemple, la commande suivante met à jour le gestionnaire de rappel associé à webhook1:

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

Voici un exemple de réponse :

{
  "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"
}

Activer ou désactiver un webhook à l'aide de l'API

Activez ou désactivez un webhook en envoyant une requête POST à /mint/organizations/{org_name}/webhooks/{webhook_id}, comme vous l'avez fait pour mettre à jour un webhook, et définissez l'attribut enabled dans le corps de la requête sur "true" ou "false", respectivement. Si vous désactivez le webhook, il ne sera pas déclenché lorsqu'un événement se produit.

Par exemple, la ligne suivante active 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

Voici un exemple de réponse :

{
  "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"
}

Supprimer un webhook à l'aide de l'API

Supprimez un webhook en envoyant une requête DELETE à /mint/organizations/{org_name}/webhooks/{webhook_id}.

Pour spécifier si vous souhaitez forcer la suppression du webhook en cas de processus en cours, définissez le paramètre de requête forceDelete sur true ou false. Le paramètre de requête forceDelete est activé (true) par défaut.

Par exemple, la commande suivante supprime webhook3:

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

Configurer le gestionnaire de rappel

Vous trouverez ci-dessous le format de la requête JSON envoyée au gestionnaire de rappel défini par un webhook lorsqu'une notification d'événement est déclenchée. Vous devez vous assurer que le gestionnaire de rappel traite la requête de manière appropriée.

{
        "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}"
}

Configurer des notifications pour un forfait ajustable

Configurez des notifications à l'aide de webhooks pour un forfait ajustable à l'aide de l'interface utilisateur ou de l'API.

Configurer des notifications pour un plan tarifaire ajustable à l'aide de l'interface utilisateur

Configurez des notifications à l'aide de webhooks pour un plan tarifaire ajustable à l'aide de l'interface utilisateur, comme décrit ci-dessous.

Accéder à la boîte de dialogue "Notifications" pour un forfait ajustable

Accédez à la boîte de dialogue "Notifications" d'un forfait ajustable, comme décrit ci-dessous.

Edge

Pour accéder à la boîte de dialogue des notifications à l'aide de l'interface utilisateur Edge:

  1. Créez et publiez un plan tarifaire de notification ajustable, comme décrit dans la section Spécifier les détails du plan de notification ajustable.
  2. Pour accéder à la page "Plans tarifaires", sélectionnez Publier > Monétisation > Plans tarifaires dans la barre de navigation de gauche.
  3. Placez le curseur sur le plan tarifaire de notification ajustable publié pour afficher les actions.
  4. Cliquez sur + Notifier.

    La boîte de dialogue "Notifications" s'affiche.

    Remarque: Le plan tarifaire doit être publié pour que l'action + Notifier s'affiche.

Edge classique (cloud privé)

Pour accéder à la page "Notifications" :

  1. Créez un plan de notification ajustable, comme décrit dans la section Spécifier les détails du plan de notification ajustable.
  2. Sélectionnez Publier > Packages pour afficher les plans tarifaires.
  3. Cliquez sur +Notifier dans la colonne "Actions" du plan tarifaire.

    La boîte de dialogue Notifications s'affiche.

Ajouter des notifications pour un plan tarifaire ajustable à l'aide de l'interface utilisateur

Pour ajouter des notifications pour un plan tarifaire ajustable dans l'interface utilisateur:

  1. Accédez à la boîte de dialogue "Notifications".
  2. Définissez la condition de notification sous Intervalles de notification en spécifiant un pourcentage du nombre cible de transactions à partir duquel vous souhaitez déclencher une notification. Plus précisément :
    • Pour définir un pourcentage exact, saisissez-le dans le champ À/De % et laissez le champ À % vide.
    • Pour définir une plage de pourcentages, saisissez les pourcentages de début et de fin dans les champs À/De % et À %, respectivement, et une valeur d'incrément dans le champ Étape %. Par défaut, les notifications sont envoyées par incréments de 10 % dans la plage spécifiée.

    Le champ Notify At est mis à jour pour refléter chaque pourcentage du nombre cible de transactions qui déclenchera un événement.

  3. Pour définir des conditions de notification supplémentaires, cliquez sur + Ajouter, puis répétez l'étape 4.
  4. Définissez l'action de notification sous Webhooks en sélectionnant un ou plusieurs webhooks pour gérer la gestion des rappels lorsque les notifications sont déclenchées.
  5. Cliquez sur Créer une notification.

Modifier les notifications d'un plan tarifaire ajustable à l'aide de l'interface utilisateur

Pour modifier les notifications d'un plan tarifaire ajustable dans l'interface utilisateur:

  1. Accédez à la boîte de dialogue des notifications.
  2. Cliquez sur + Notifier dans la colonne "Actions" du forfait.
  3. Cliquez sur Modifier.
  4. Modifiez les valeurs si nécessaire.
  5. Cliquez sur Enregistrer la notification.

Supprimer les notifications d'un plan tarifaire ajustable à l'aide de l'UI

Pour supprimer une condition et une action de notification:

  1. Accédez à la boîte de dialogue des notifications.
  2. Cliquez sur +Notifier dans la colonne "Actions" du plan tarifaire.
  3. Cliquez sur Supprimer la notification.

Configurer des notifications pour un plan tarifaire ajustable à l'aide de l'API

Pour configurer une notification pour un forfait ajustable à l'aide de l'API, suivez la procédure décrite dans la section Gérer les conditions et les actions de notification à l'aide de l'API et utilisez les attributs décrits dans cette section.

Pour configurer la condition de notification (notificationCondition), utilisez les valeurs d'attribut suivantes. Pour en savoir plus, consultez la section Propriétés de configuration des conditions de notification.

Attribut Valeur
RATEPLAN ID du forfait de notifications ajustable.
PUBLISHED TRUE pour indiquer que le plan tarifaire de notification ajustable doit être publié.
UsageTarget Pourcentage du nombre cible de transactions à partir duquel vous souhaitez déclencher une notification.

Cet attribut vous permet d'avertir les développeurs lorsqu'ils atteignent ou approchent leur nombre cible de transactions pour un forfait de carte de taux de notification ajustable qu'ils ont acheté. Par exemple, si un développeur a acheté un forfait de notifications ajustable et que le nombre cible de transactions a été défini sur 1 000, vous pouvez le prévenir lorsqu'il atteint 800 transactions (80% du nombre cible de transactions), 1 000 transactions (100%) ou 1 500 transactions (150%).

  • Pour définir un pourcentage exact, saisissez %= n. Par exemple, %= 80 envoie des notifications lorsque le pourcentage du nombre cible de transactions atteint 80%.
  • Pour définir une plage de pourcentages, saisissez les pourcentages de début et de fin, ainsi que la valeur d'incrémentation, comme suit: %= start to end by n. Par exemple, une valeur de %= 80 to 100 by 10 envoie des notifications lorsque le pourcentage du nombre cible de transactions atteint 80%, 90 % et 100%.

Pour configurer l'action de notification, sous actions, définissez les valeurs suivantes. Pour en savoir plus, consultez la section Propriétés de configuration pour les actions de notification.

Attribut Valeur
actionAttribute WEBHOOK pour déclencher un webhook.
value ID du webhook que vous avez défini dans la section précédente, Créer des webhooks à l'aide de l'API.

Vous trouverez ci-dessous un exemple de création d'une condition de notification qui déclenche un webhook lorsque le pourcentage du nombre cible de transactions atteint 80%, 90%, 100%, 110 % et 120%.

{
    "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",
        }]
  }

Pour savoir comment afficher, mettre à jour et supprimer une condition et une action de notification, consultez les pages suivantes:

Codes de réponse webhook

Vous trouverez ci-dessous un récapitulatif des codes de réponse des webhooks et de leur interprétation par le système.

Code de réponse Description
2xx Opération réussie
5xx

Échec de la requête. Le système réessayera la requête jusqu'à trois fois à intervalles de cinq minutes.

Remarque : Les délais avant expiration de la lecture et de la connexion pour les requêtes webhook sont de trois secondes chacun, ce qui peut entraîner l'échec des requêtes.
Other response Échec de la requête. Le système ne réessayera pas la requête.