> ## Documentation Index > Fetch the complete documentation index at: https://docs.metronome.com/llms.txt > Use this file to discover all available pages before exploring further. # Créer des spécificateurs d'alertes 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](https://docs.metronome.com/api-reference/custom-fields#custom-fields). 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ÉS** `alert_specifiers[].custom_field_filter` avec une `key` et une `value` spécifiques fonctionne de manière identique au [`custom_field_filter`](https://docs.metronome.com/api-reference/alerts/create-a-threshold-notification#body-custom-field-filters) 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. ```json theme={null} 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 GROUPE** Le 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. ```json theme={null} 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. ```json theme={null} { "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. ```json theme={null} { "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" } ] } ] } } ``` **INFO** Vous 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ÉCIFICATEUR** Les 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. ```json theme={null} 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. ```json theme={null} 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 : ```json theme={null} { "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é.