Passer au contenu principal
Metronome vous permet de configurer certaines alertes avec des conditions d’inclusion et d’exclusion plus granulaires à l’aide de spécificateurs d’alertes. Par défaut, une alerte low_remaining_contract_credit_and_commit_balance_reached évalue le solde combiné de tous les engagements et crédits actifs d’un client. Lorsque ce total descend sous le seuil configuré, vous recevez une seule notification. Avec les spécificateurs d’alertes, vous pouvez modifier ce qui est évalué :
  • Inclure uniquement les engagements et crédits qui correspondent à un ensemble spécifique de valeurs de champs personnalisés
  • Exclure les engagements et crédits qui correspondent à certaines conditions de champs personnalisés
  • Regrouper les évaluations de solde par clé de champ personnalisé, afin de recevoir une notification distincte pour chaque valeur unique de cette clé
Cela permet des schémas tels que :
  • Déclencher une alerte lorsque le solde de crédits spécifiques à un produit (par exemple, des crédits étiquetés product_family: abc) tombe sous un seuil, indépendamment de votre pool général de crédits
  • Déclencher une alerte lorsqu’un engagement individuel (par exemple, des engagements étiquetés avec unique_id: commit_xyz) tombe sous un seuil
  • Exclure certains crédits perpétuels d’une alerte de solde général afin qu’elle ne se déclenche que lorsque vos crédits standard sont bas

​
Comment fonctionnent les spécificateurs d’alertes

Les spécificateurs d’alertes sont définis dans le tableau alert_specifiers d’une alerte low_remaining_contract_credit_and_commit_balance_reached. Chaque spécificateur contient :
  • custom_field_filters : un tableau de conditions d’inclusion qui définit quels engagements et crédits sont pris en compte pour cette alerte. S’il est omis, tous les engagements et crédits sont inclus. Si une key est spécifiée sans value, l’alerte regroupe les évaluations par chaque valeur unique de cette clé.
  • exclude : un tableau de conditions d’exclusion. Les engagements et crédits correspondant à une condition d’exclusion sont retirés de l’évaluation, même s’ils satisfont aux conditions d’inclusion.
Les spécificateurs d’alertes filtrent sur les champs personnalisés. Vous pouvez définir des champs personnalisés sur tout engagement ou crédit lors de sa création. Pour en savoir plus sur la définition et l’affichage des champs personnalisés, consultez ici. La définition ou la mise à jour d’une valeur de champ personnalisé sur un crédit ou un engagement déclenchera une réévaluation de toute alerte de solde utilisant les alert_specifiers applicables à ce crédit ou engagement.

​
Inclure des paires clé-valeur spécifiées

Lorsque vous fournissez custom_field_filters avec une key et une value spécifiques, seuls les engagements et crédits correspondant à toutes ces conditions sont comptabilisés pour le seuil d’alerte. Plusieurs spécificateurs dans le tableau alert_specifiers sont évalués comme des conditions OU — un engagement ou crédit doit correspondre à un seul spécificateur pour être inclus. Au sein du tableau custom_field_filters d’un seul spécificateur, plusieurs conditions sont évaluées comme ET — un engagement ou crédit doit correspondre à toutes les conditions listées pour être inclus.
SPÉCIFICATEURS D’ALERTES VS. FILTRES DE CHAMPS PERSONNALISÉSalert_specifiers[].custom_field_filter avec une key et une value spécifiques fonctionne de manière identique au custom_field_filter de niveau supérieur lors de la création d’une alerte. Utilisez alert_specifiers pour plus de flexibilité.
Imaginez que vous accordez une promotion de crédits gratuits le 4 mai à un sous-ensemble de clients et que vous voulez savoir quand les crédits promotionnels d’un client atteignent $0. Créez une alerte qui se déclenche uniquement lorsque les crédits étiquetés promo_code: may_the_fourth atteignent un seuil de $0. 
POST /v1/alerts/create
{
  "name": "May the Fourth be with you promo alert",
  "alert_type": "low_remaining_contract_credit_and_commit_balance_reached",
  "threshold": 0,
  "alert_specifiers": [
    {
      "custom_field_filters": [
         {
            "entity": "ContractCredit",
            "key": "promo_code",
            "value": "may_the_fourth"
          }
       ]
    }
  ]
}

​
Inclure toutes les valeurs uniques d’une clé spécifiée

Lorsque vous fournissez une entrée custom_field_filters avec une key mais sans value, Metronome évalue le solde séparément pour chaque valeur unique de cette clé. Un webhook est envoyé si le solde total pour tous les soldes étiquetés avec une paire clé-valeur de champ personnalisé est inférieur au seuil de notification, puis ensuite lorsque tout autre groupe de soldes avec la même clé mais des valeurs différentes atteint le seuil. Un webhook initial de niveau supérieur sera envoyé la première fois qu’une paire clé-valeur avec la clé définie atteint le seuil.
UNE SEULE CLÉ DE GROUPELe regroupement par clé nécessite un seul spécificateur avec une seule key et sans value. Vous ne pouvez pas regrouper par plus d’une clé à la fois.
Imaginez que votre entreprise propose plusieurs crédits promotionnels différents à la fois. Un seul client peut avoir plusieurs promotions en cours et veut être alerté lorsque chaque crédit promotionnel individuel atteint $0. Au lieu de créer une alerte dédiée à chaque promotion, créez une alerte de solde groupée pour toutes les promotions. 
POST /v1/alerts/create
{
  "name": "Parent promo alert",
  "alert_type": "low_remaining_contract_credit_and_commit_balance_reached",
  "threshold": 0,
  "alert_specifiers": [
    {
      "custom_field_filters": [
         {
            "entity": "ContractCreditorCommit",
            "key": "promo_code"
          }
       ]
    }
  ]
}
Pour chaque crédit promotionnel donné, créez le crédit avec la clé de champ personnalisé promo_code et le nom de la promotion. L’alerte sera automatiquement appliquée à tous les clients et à toutes les promotions actuelles et futures sans aucune modification de code nécessaire. Lorsqu’un crédit promotionnel spécifique d’un client atteint le seuil, vous recevez un webhook pour cette paire clé-valeur spécifique qui a franchi le seuil. Le champ alert_specifiers dans la charge utile inclut la key et la value qui ont déclenché la notification. 
{
  "id": "notif_abc123",
  "type": "alerts.low_remaining_contract_credit_and_commit_balance_reached",
  "properties": {
    "customer_id": "cust_123",
    "alert_id": "alert_id",
    "alert_name": "Parent promo alert",
    "timestamp": "2026-05-07T15:08:44.865Z",
    "threshold": 0,
    "credit_type_id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
    "alert_specifiers": [
      {
        "custom_field_filters": [
          {
            "entity": "ContractCreditOrCommit",
            "key": "promo_code",
            "value": "may_7th_promo"
          }
        ]
      }
    ]
  }
}
S’il s’agit de la première paire clé-valeur à franchir le seuil, vous recevrez également une notification supplémentaire pour l’alerte globale. Ce webhook omet le champ value spécifique dans custom_field_filters, indiquant qu’il s’applique à l’alerte dans son ensemble. 
{
  "id": "notif_def456",
  "type": "alerts.low_remaining_contract_credit_and_commit_balance_reached",
  "properties": {
    "customer_id": "cust_123",
    "alert_id": "alert_id",
    "alert_name": "Parent promo alert",
    "timestamp": "2026-05-07T15:08:44.866Z",
    "threshold": 0,
    "credit_type_id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
    "alert_specifiers": [
      {
        "custom_field_filters": [
          {
            "entity": "ContractCreditOrCommit",
            "key": "promo_code"
          }
        ]
      }
    ]
  }
}
INFOVous pouvez configurer jusqu’à 3 alertes de solde par clé pour un seul client avec une prise en charge jusqu’à 1 000 de cardinalité (paires clé-valeur uniques) par clé de groupe. Pour les clés ayant plus de 1 000 valeurs, contactez votre représentant Metronome pour discuter de votre configuration de spécificateurs d’alertes.

​
Exclure des paires clé-valeur spécifiées

Le champ exclude au sein d’un spécificateur retire des engagements ou crédits spécifiques d’un ensemble par ailleurs inclusif. Plusieurs entrées d’exclusion sont évaluées comme des conditions OU — un engagement ou crédit est exclu s’il correspond à l’une d’elles.
LES ENTITÉS EXCLUES DOIVENT ÊTRE INCLUSES DANS LE MÊME SPÉCIFICATEURLes conditions d’exclusion doivent cibler des entités qui se trouvent dans le périmètre d’inclusion du même spécificateur. Par exemple, vous ne pouvez pas créer un seul spécificateur d’alerte qui inclut des engagements mais exclut des crédits.
Créez une alerte qui se déclenche lorsque le solde de crédits général (non spécifique à un produit) tombe sous un seuil. Les crédits étiquetés is_product_specific: true sont exclus de cette évaluation. 
POST /v1/alerts/create
{
  "customer_id": "cust_abc123",
  "name": "General credit balance alert",
  "alert_type": "low_remaining_contract_credit_and_commit_balance_reached",
  "threshold": 10000,
  "alert_specifiers": [
    {
      "exclude": [
        {
          "custom_field_filters": [
            {
              "entity": "ContractCreditOrCommit",
              "key": "is_product_specific",
              "value": "true"
            }
          ]
        }
      ]
    }
  ]
}

​
Récupération du statut d’une alerte

Vous pouvez récupérer le statut actuel d’une alerte avec des spécificateurs en utilisant POST /v1/customer-alerts/get. Pour récupérer le statut d’une paire clé-valeur de champ personnalisé spécifique, passez soit custom_field_filters, soit alert_specifiers dans le corps de la requête. 
POST /v1/customer-alerts/get
{
  "alert_id": "alert_id",
  "customer_id": "cust_123",
  "alert_specifiers": [
    {
      "custom_field_filters": [
        {
          "entity": "ContractCreditOrCommit",
          "key": "promo_code",
          "value": "may_7th_promo"
        }
      ]
    }
  ]
}
La requête retournera le statut de la paire clé-valeur spécifiée : 
{
  "data": {
    "customer_status": "in_alarm",
    "alert": {
      "id": "alert_id",
      "name": "Per-product-family balance alert (excluding data compression)",
      "alert_type": "low_remaining_contract_credit_and_commit_balance_reached",
      "status": "active",
      "threshold": 0,
      "alert_specifiers": [
        {
          "custom_field_filters": [
            {
              "entity": "ContractCreditOrCommit",
	          "key": "promo_code",
		         "value": "may_7th_promo"
            }
          ]
        }
      ]
    }
  }
}

​
Webhooks de résolution

Recevez un webhook low_remaining_contract_credit_and_commit_balance_resolved lorsqu’une alerte revient à OK depuis IN_ALARM. Contactez votre représentant Metronome si vous avez besoin que cela soit activé.