Passer au contenu principal
Metronome fournit des notifications programmatiques sous forme de webhooks. Si vous configurez une URL de webhook, Metronome envoie une requête HTTP POST à cette URL lorsque certains événements se produisent, comme la création d’un contrat, l’atteinte d’un seuil ou la finalisation d’une facture. Votre service peut alors réagir à cette notification en mettant à jour l’état du client, en envoyant un e-mail ou en notifiant les utilisateurs internes pour qu’ils prennent une action.

​
Types de webhooks

Metronome envoie ces types de webhooks : Notifications de seuil alerts.<notification_type> Les notifications de seuil surveillent les métriques en temps réel et se déclenchent lorsque des seuils définis sont franchis. Consultez notre documentation sur les notifications de seuil pour en savoir plus sur la configuration de ces types de notifications Les notifications de seuil ont cette structure : 
{  
  "id": "445b849e-1366-4580-a6cc-f488e27c059f",  
  "properties": {  
    "customer_id": "ac39ecc3-87ee-4d58-8ec0-24041464dddd",  
    "alert_id": "445b849e-1366-4580-a6cc-f488e27c059f",  
    "timestamp": "2024-10-07T15:08:44.865Z",  
    "threshold": 20000,  
    "alert_name": "Credit balance low",  
    "credit_type_id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",  
    "remaining_balance": 5000,  
    "triggered_by": "usage"  
  },  
  "type": "alerts.low_remaining_credit_balance_reached"  
}
Notifications système pour les événements liés aux contrats, crédits et engagements contract.<notification_type> commit.<notification_type> credit.<notification_type> Les notifications système surveillent quand des événements ou des actions se produisent en fonction de l’horodatage configuré d’un objet (par exemple, le début d’un contrat) ou de l’heure à laquelle une action s’est produite (par exemple, la création d’un contrat). Consultez notre documentation sur les notifications système pour en savoir plus sur la configuration de ces types de notifications Les notifications système ont cette structure : 
{
  "id": "fca7b4ef-6187-51d5-a9d9-b57f40117728",
  "type": "contract.create",
  "timestamp": "2025-09-12T20:20:04Z",
  "environment_type": "PRODUCTION",
  "contract_id": "33d206f6-7455-49f6-857d-2172c37db68d",
  "contract_custom_fields": {
    "org_key": "g_major"
  },
  "customer_id": "1ed86915-97f1-4d92-8fa6-763c0235093a",
  "customer_custom_fields": {
    "bill_customer_id": "0cu21JDIRIUDQKDS6wmx"
  }
}
Notifications décalées pour les événements liés aux contrats, crédits et engagements Les notifications décalées vous permettent de planifier des notifications à déclencher par rapport à une date connue (par exemple, la date de fin d’un engagement ou la date de création d’un contrat). Consultez notre documentation sur les notifications décalées pour en savoir plus sur la configuration de ces types de notifications Les notifications décalées ont cette structure : 
{
  "id": "c9656215-3e96-59f4-7284-0021bdfd4c9a",
  "type": "contract.start",
  "timestamp": "2025-07-02T00:00:00Z",
  "environment_type": "PRODUCTION",
  "contract_id": "1bd74703-0854-4730-9549-893585c519e8",
  "contract_custom_fields": {
    "ContractType": "PayGo"
  },
  "customer_id": "eadab230-ef95-4c3c-d696-4391c205c982",
  "customer_custom_fields": {
    "CustomerType": "Tier2"
  },
  "offset_id": "8ed3d961-7b61-4c0a-8f2b-e546f45c33d6",
  "offset_duration": "-P3DT12H" // signed ISO-8601 duration
}
Notifications de finalisation de facture invoice.finalized Déclenché chaque fois qu’une facture est finalisée (se produit après la période de grâce). Les notifications de finalisation de facture ont cette structure : 
{
  "id": "fc00bd44-8d4b-4913-9b7c-fd1f8da61e62",
  "properties": {
    "invoice_id": "de99894e-f9ce-4b6c-92b0-f4ec0d09b6f1",
    "customer_id": "3c9e87ba-0e49-44a3-9aa9-6917f8da3491",
    "invoice_finalized_date": "2024-02-20T15:50:07.457Z"
  },
  "type": "invoice.finalized"
}
CONFIGURATION DES NOTIFICATIONSParlez à votre représentant Metronome pour configurer les notifications invoice.finalized.
Notifications d’erreur de fournisseur de facturation (Stripe) invoice.billing_provider_error Les webhooks d’erreur de fournisseur de facturation s’appliquent uniquement à Stripe et sont déclenchés chaque fois qu’il y a une erreur dans l’envoi d’une facture à Stripe (par exemple, le client n’existe pas dans Stripe ou le client n’a pas de méthode de paiement valide). Aucune configuration supplémentaire n’est nécessaire pour ce webhook ; les notifications sont envoyées automatiquement lorsqu’une destination de webhook est configurée et que l’intégration Stripe est activée sur le compte. Notez qu’aucun webhook Metronome n’est déclenché pour les erreurs résidant entièrement dans Stripe (comme les échecs de paiement). Les notifications d’erreur de fournisseur de facturation ont cette structure : 
{
  "id": "c941cccc-a890-45e4-96de-3fdb8a6809f3",
  "properties": {
    "invoice_id": "9927e175-c1d3-4f94-875b-8906bc773a95",
    "customer_id": "83518c41-76ff-4ac4-85d4-bd7010112bd3",
    "billing_provider": "STRIPE",
    "billing_provider_error": "No such customer: 'cus_PQzIVPOCGb4otV'"
  },
  "type": "invoice.billing_provider_error"
}
Problèmes d’intégration integration.issue Les webhooks de problème d’intégration sont déclenchés lorsqu’il y a une erreur avec l’intégration tierce du client (par exemple, identifiants invalides, connexions mal configurées ou erreurs API). Aucune configuration supplémentaire n’est nécessaire ; les notifications sont envoyées automatiquement lorsqu’une destination de webhook est configurée et que l’intégration est activée. Les notifications de problème d’intégration ont cette structure : 
{
  "id": "c941cccc-a890-45e4-96de-3fdb8a6809f3",
  "type": "integration.issue",
  "properties": {
    "integration": "NETSUITE",
    "error": "Authentication failed: Invalid client credentials",
    "error_code": "INVALID_CREDENTIALS",
    "timestamp": "2025-10-03T12:34:56.789Z"
  }
}
Notifications du marketplace AWS marketplaces.aws_metering_disabled Déclenché lorsqu’un client du marketplace AWS est désactivé Les notifications de mesure du marketplace AWS ont cette structure : 
{
  "id": "daf54f25-12f4-4b2a-8462-ebfff4b622b7",
  "properties": {
    "customer_id": "4ffe51f1-3702-490c-816e-35fad3e271de",
    "aws_customer_id": "SJyeYLq7123",
    "aws_product_code": "6m81ochldaiejgnw0b8391bfn"
  },
  "type": "marketplaces.aws_metering_disabled"
}
Notifications du marketplace Azure marketplaces.azure_metering_disabled Déclenché lorsqu’un client du marketplace Azure est désactivé Les notifications de mesure du marketplace Azure ont cette structure : 
{
  "id": "c9afa306-4449-45f3-9bce-68e4927a1f0b",
  "properties": {
    "customer_id": "1eea08e0-2fe0-45ad-96e2-3c1dbc2ce3a8",
    "subscription_id": "f6ccac8e-9918-4c8f-9597-8a210a84c31c"
  },
  "type": "marketplaces.azure_metering_disabled"
}
Notifications du marketplace GCP marketplaces.gcp_metering_disabled Déclenché lorsqu’un client du marketplace GCP est désactivé Les notifications de mesure du marketplace GCP ont cette structure : 
{
  "id": "c9afa306-4449-45f3-9bce-68e4927a1f0b",
  "properties": {
    "customer_id": "1eea08e0-2fe0-45ad-96e2-3c1dbc2ce3a8",
    "gcp_usage_reporting_id": "project_number:012345678912",
    "gcp_entitlement_id": "f6ccac8e-9918-4c8f-9597-8a210a84c31c",
    "gcp_service_name": "your-listing.endpoints.provider.cloud.goog"
  },
  "type": "marketplaces.gcp_metering_disabled"
}

​
Notifications de gating de paiement

Les notifications de gating de paiement sont liées à des workflows spécifiques dans Metronome qui conditionnent l’accès à un produit (par exemple, le solde d’engagement) en fonction de la collecte réussie du paiement. Seuil de paiement atteint Ce webhook est déclenché lorsqu’une action de gating de paiement est déclenchée, par exemple lorsqu’un client atteint son threshold_amount pour la facturation par seuil. Statut de la barrière de paiement Après une tentative de paiement pour un workflow de barrière de paiement, ce webhook renvoie le statut. Il inclut les métadonnées pertinentes de la passerelle, telles que les codes d’erreur, le cas échéant. Action requise pour la barrière de paiement Ce webhook est déclenché si une action supplémentaire est nécessaire pour compléter le paiement. Il inclut les métadonnées pertinentes pour identifier le paiement associé dans la passerelle, le cas échéant. Workflow externe initié Si le traitement du paiement passe par une passerelle externe en dehors d’une intégration native Metronome, ce webhook vous fournira les informations pour traiter cette transaction. Le workflow_id fourni est utilisé pour libérer ou annuler le solde, en attendant le résultat du paiement. Les notifications de gating de paiement ont cette structure : 
{  
  "id": "d304936c-a287-492c-b546-ac79dc673191",  
  "properties": {  
    "workflow_type": "manual_commit",     
    "customer_id": "6352d562-213f-4a6e-819f-58fdabc3f2b9",  
    "contract_id": "bbf87cf7-beaa-4d96-aea4-2cd87009dcb6",  
    "invoice_id": "6644b5ec-394a-4d07-a037-e2827a0af4be",  
    "payment_status": "failed",  
    "timestamp": "2025-01-01T00:00:00Z",  
    "error_message": "Your card has insufficient funds.",  
    "billing_provider": {  
        "type": "stripe",  
        "stripe": {  
            "payment_intent_id": "pi_3RP3ioIkTQSg6Mm31jR006rF",  
            "error": {  
                "type": "card_error",  
                "code": "card_declined",  
                "decline_code": "insufficient_funds",  
                "message": "Your card has insufficient funds."  
            },  
        },  
    },  
  },  
  "type": "payment_gate.payment_status"  
}  

{  
  "id": "417fcaa4-f3cf-434e-ab20-f70204cfd5ef",  
  "properties": {  
    "workflow_type": "spend",     
    "customer_id": "d290dec8-4ebb-4e73-89ef-45ed3443ca67",  
    "contract_id": "80b07d70-c84e-4ff0-b42c-875defff0931",  
    "invoice_id": "dd864572-9787-573f-9c74-e5159b4ea97c",  
    "error_message": "three_d_secure_redirect",  
    "billing_provider": {  
        "type": "stripe",  
        "stripe": {  
            "payment_intent_id": "pi_3ROpJCIkTQSg6Mm31fNUnPKx",  
        },  
    },  
  },  
  "type": "payment_gate.payment_pending_action_required"  
}  

{  
  "id": "417fcaa4-f3cf-434e-ab20-f70204cfd5ef",  
  "properties": {  
    "workflow_type": "spend",     
    "customer_id": "d290dec8-4ebb-4e73-89ef-45ed3443ca67",  
    "contract_id": "80b07d70-c84e-4ff0-b42c-875defff0931",  
    "timestamp": "2025-01-01T00:00:00.000Z",  
  },  
  "type": "payment_gate.threshold_reached"  
}  

{  
  "id": "417fcaa4-f3cf-434e-ab20-f70204cfd5ef",  
  "properties": {  
    "workflow_type": "spend",     
    "customer_id": "d290dec8-4ebb-4e73-89ef-45ed3443ca67",  
    "contract_id": "80b07d70-c84e-4ff0-b42c-875defff0931",  
    "workflow_id": "d7abd0cd-4ae9-4db7-8676-e986a4ebd8dc",  
    "invoice_id": "6a37bb88-8538-48c5-b37b-a41c836328bd",  
    "invoice_total": 1500,  
    "invoice_currency": "USD",  
  },  
  "type": "payment_gate.external_initiate"  
}

​
Adresses IP des webhooks

Les notifications webhook peuvent provenir des adresses IP suivantes. Cette liste peut changer, mais si c’est le cas, nous donnerons un préavis d’au moins 30 jours. 
52.39.198.29
44.241.254.184
52.42.224.184
52.89.217.131
44.231.139.128
54.245.125.92
3.134.178.31
3.12.62.53
3.140.90.67
3.142.231.113
3.131.206.70
3.132.225.181

​
Gérer les notifications webhook

Pour recevoir les webhooks Metronome, vous avez besoin d’un gestionnaire de webhook écoutant sur une URL HTTPS accessible publiquement qui effectue les tâches ci-dessous.

​
Accuser réception de la notification

Lors de la réception d’une notification, votre point de terminaison doit renvoyer un code de statut de réussite, comme 200 OK. Si Metronome reçoit un code de statut > 299, des tentatives de notification sont effectuées jusqu’à ce qu’un code de statut de réussite soit renvoyé. Si votre point de terminaison webhook n’accuse pas correctement réception de la notification, Metronome la retente en continu avec un backoff exponentiel jusqu’à atteindre une cadence de réessai de 15 minutes. Une fois que le processus de réessai atteint 15 minutes, Metronome répète la notification jusqu’à ce qu’elle soit acceptée ou que deux jours se soient écoulés depuis la tentative de notification initiale (~200 réessais). Il est recommandé de traiter les webhooks de manière asynchrone : stockez la charge utile du webhook dans une file d’attente, renvoyez un code de réponse 200, puis seulement validez ou traitez la charge utile. Retirer le traitement webhook du chemin de réception réduit le risque de blocage de vos systèmes.

​
Préparez-vous aux notifications en double

Dans des circonstances normales, Metronome envoie chaque notification exactement une fois. Cependant, il y a quelques situations qui pourraient vous amener à recevoir la même notification plusieurs fois :
  • Réessais — comme mentionné ci-dessus, si Metronome reçoit une erreur en tentant de livrer la notification à votre gestionnaire de webhook, nous retentons la notification. Selon la nature de l’erreur, il est possible que votre point de terminaison reçoive une notification sans l’accuser, auquel cas votre point de terminaison recevra à nouveau la même notification.
  • Plusieurs URL de webhook — si vous configurez Metronome pour notifier plusieurs URL de webhook, ou même la même URL plusieurs fois, les notifications sont envoyées plusieurs fois. Si vous voulez vous assurer que les notifications en double sont ignorées, vous pouvez utiliser le champ id de la notification pour dédupliquer.

​
Vérifier les notifications

Étant donné que votre point de terminaison webhook est une URL publique, n’importe qui peut lui envoyer une requête. Avant de prendre des actions basées sur la notification, vous devez vérifier les informations qu’elle contient. Vous pouvez le faire de deux manières : en récupérant vous-même les données de l’API Metronome ou en vérifiant la signature de la requête webhook.
INFOMetronome peut introduire des modifications rétrocompatibles aux formes de webhook existantes sans préavis, comme l’ajout d’un nouveau champ webhook. Metronome recommande de ne valider que les champs qui sont censés être présents selon la documentation au moment de l’intégration.

​
Appelez l’API Metronome

Les notifications webhook ne contiennent que des informations minimales sur l’événement qui s’est produit. Cela signifie qu’il est souvent utile d’appeler le point de terminaison API Metronome approprié pour obtenir les détails complets. Par exemple, si vous recevez une notification webhook vous informant qu’une facture a été finalisée, vous pouvez appeler le point de terminaison /customers/{customer_id}/invoices/{invoice_id} pour récupérer les détails de la facture mentionnée dans la notification. Ainsi, la notification sert d’indice que quelque chose a changé, mais votre code ne dépend que des données obtenues directement de l’API Metronome.

​
Vérifier les signatures

Si la stratégie ci-dessus ne fonctionne pas pour votre cas d’usage, Metronome fournit également une méthode pour vérifier l’authenticité des notifications au fur et à mesure que vous les recevez en utilisant l’en-tête HTTP Metronome-Webhook-Signature. La valeur de cet en-tête est une signature cryptographique de la requête HTTP, utilisant une clé secrète configurée lorsque vous configurez votre webhook.
Les clés secrètes sont uniques par webhookSi vous avez plusieurs webhooks configurés sur votre compte Metronome, chaque webhook a sa propre clé secrète.
Pour valider la signature, concaténez d’abord la valeur de l’en-tête X-Metronome-Date de la requête et les octets exacts du corps de la requête, séparés par un caractère de nouvelle ligne (\n). Calculez ensuite le HMAC-SHA256 de la chaîne résultante, en utilisant la clé secrète du webhook comme clé. Enfin, comparez la représentation hexadécimale du HMAC que vous avez calculé avec celle trouvée dans l’en-tête Metronome-Webhook-Signature. Si elles ne correspondent pas, la notification webhook ne provient pas de Metronome. 
HMAC_SHA256(secret_key, X_METRONOME_DATE_HEADER + "\n" + BODY)
Utilisez X-Metronome-Date au lieu de DateMetronome envoie à la fois un en-tête X-Metronome-Date et un en-tête Date standard avec la même valeur. Préférez X-Metronome-Date pour la vérification de signature : il est préservé de bout en bout et n’est pas réécrit par des intermédiaires (équilibreurs de charge, proxys ou frameworks) qui pourraient écraser l’en-tête Date standard, ce qui ferait échouer la vérification de signature. L’en-tête Date est toujours pris en charge pour la rétrocompatibilité, mais n’est pas recommandé.
L’en-tête X-Metronome-Date est inclus pour aider à la déduplication. Vous devez ignorer les requêtes webhook qui ont plus de cinq minutes, ce qui signifie que votre gestionnaire de webhook n’a qu’à stocker les ID de notification récents pour éviter les doublons.
LE CORPS DOIT ÊTRE TRAITÉ COMME DES OCTETSLors du calcul de la signature, Metronome utilise les octets exacts envoyés dans le corps de la requête. Faites attention à faire de même dans votre code. Si vous essayez d’utiliser le corps JSON analysé à des fins de vérification, vous échouerez probablement à la vérification de signature car la sérialisation des données à nouveau n’est pas garantie de produire le même JSON.
L’exemple de code suivant montre comment effectuer la validation de signature : 
echo -n "$X_METRONOME_DATE_HEADER\n$BODY" | openssl dgst -sha256 -hmac $KEY
Pour tester cela, considérez l’exemple de notification webhook suivant. La clé secrète pour la vérification est correct-horse-battery-staple : 
POST /webhook HTTP/1.1
Host: example.com
User-Agent: Metronome
Content-Type: application/json
Date: Mon, 02 Jan 2006 22:04:05 GMT
X-Metronome-Date: Mon, 02 Jan 2006 22:04:05 GMT
Metronome-Webhook-Signature: b82652fa2246cf1d8a27e591f155c865f68b46c19b9213fd9c052f2419b4742b

{
  "id": "b2c9e307-624e-4e7d-a5a4-1b74107d78c4",
  "type": "widget_created",
  "properties": {
    "customer_id": "5f794d50-085a-4db6-8d15-286e518b7225",
    "widget_id": "0891458d-b6f0-4fdd-a41e-380aae1a1e38"
  }
}

​
Envoyer des webhooks à Slack

Si vous voulez recevoir les notifications Metronome dans Slack sans construire de gestionnaire webhook personnalisé, vous pouvez configurer Metronome pour envoyer les notifications directement à un canal Slack. À partir de là, vous pouvez les trier et agir sur elles. Pour envoyer les webhooks Metronome à Slack : Pour envoyer les webhooks Metronome à Slack :
  1. Créez un webhook entrant dans Slack et copiez l’URL de webhook générée. Elle ressemblera à : https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX
  2. Créez une destination de webhook dans Metronome pour votre canal Slack. Dans l’application Metronome, allez à Connections > API tokens & webhooks > Webhooks > Add et collez votre URL de webhook Slack.
  3. Configurez une notification de test pour vérifier l’intégration. Dans l’application Metronome, allez à Connections > Notifications > Create Notification et créez une notification telle que Low credit balance reached.
  4. Vérifiez l’intégration en testant la connexion webhook. Déclenchez votre notification de test et vérifiez votre canal Slack pour un message de Metronome.
Lorsqu’il est correctement configuré, vous recevrez des messages Slack qui ressemblent à ceci : 
{
  "id": "445b849e-1366-4580-a6cc-f488e27c059f",
  "properties": {
    "customer_id": "ac39ecc3-87ee-4d58-8ec0-24041464dddd",
    "alert_id": "445b849e-1366-4580-a6cc-f488e27c059f",
    "timestamp": "2024-10-07T15:08:44.865Z",
    "threshold": 20000,
    "alert_name": "Credit balance low",
    "credit_type_id": "2714e483-4ff1-48e4-9e25-ac732e8f24f2",
    "remaining_balance": 5000,
    "triggered_by": "usage"
  },
  "type": "alerts.low_remaining_credit_balance_reached"
}