Metronome provides programmatic notifications in the form of webhooks. If you configure a webhook URL, Metronome sends an HTTP POST request to that URL when certain events occur, such as an invoice being finalized. Your service can then react to that notification by updating customer state, sending an email, and so on. Webhooks are sent for alert evaluations or for predefined system actions. Metronome notifications have this structure: 
{  
  "id": "string",   // a unique identifier for this specific notification  
  "type": "string", // the notification type  
  "properties": {  
    // additional type-specific properties to describe the notification  
  }  
}

​
Webhook Types

Metronome sends these webhook types: alerts.<alert_type> Alerts are the most common source for webhook notifications. See our alerts documentation for more on how to set these up. invoice.billing_provider_error Billing provider error webhooks only apply to Stripe and are triggered any time there is an error in sending an invoice to Stripe (for example, the customer does not exist within Stripe or the customer does not have a valid payment method). No additional configuration is needed for this webhook; notifications are automatically sent when a webhook destination is set up and the Stripe integration is enabled on the account. Note that no Metronome webhook is triggered for errors residing entirely within Stripe (such as payment failures). 
{  
  "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"  
}
invoice.finalized (beta) Triggered whenever an invoice is finalized (happens after the 24 hour grace period). 
{  
  "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"  
}
NOTIFICATION CONFIGURATIONTalk to your Metronome representative to set up invoice.finalized notifications.
marketplaces.aws_metering_disabled Triggered when an AWS marketplace customer is disabled. 
{  
    "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"  
}
marketplaces.azure_metering_disabled Triggered when an Azure marketplace customer is disabled. 
{  
    "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"  
}

​
Payment gating notifications

Payment gating alerts are tied to specific workflows in Metronome that gate access to some product (e.g. commit balance) based on successful payment collection. Payment threshold reached This webhook is fired when a payment gating action is triggered, such as when a customer hits their threshold_amount for Threshold Billing. Payment gate status After a payment is attempted for a payment gate workflow, this webhook returns the status. It includes relevant metadata from the gateway, such as error codes, if applicable. Payment gate action required This webhook is fired if an additional action is required to complete payment. It includes relevant metadata to identify the associated payment in the gateway, if applicable. External workflow initiated If processing payment via an external gateway outside of a native Metronome integration, this webhook will provide you the information to process that transaction. The workflow_id provided is used to release or cancel the balance, pending payment outcome.

​
Webhook IP Addresses

Webhook notifications may come from the following IP addresses. This list may change, but if it does we’ll give at least 30 days notice. 
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

​
Handle Webhook Notifications

To receive Metronome webhooks, you need a webhook handler listening at a publicly accessible HTTPS URL that performs the below tasks.

​
Acknowledge the Notification

Upon receiving a notification, your endpoint must return a successful status code, such as 200 OK. If Metronome receives a status code >299, notification retries are attempted until a successful status code is returned. If your webhook endpoint does not properly acknowledge the notification, Metronome continuously retries it with exponential backoff until it hits a 15-minute retry cadence. Once the retry process hits 15 minutes, Metronome repeats the notification until it is either accepted or two days have passed since the initial notification attempt (~200 retries). It is recommended that you process webhooks asynchronously: store the webhook payload in a queue, return a 200 response code, and only then validate or process the payload. Removing webhook processing from the receiving path reduces the likelihood of your systems getting blocked.

​
Prepare for Duplicate Notifications

Under normal circumstances, Metronome sends each notification exactly once. However, there are a few situations that could cause you to receive the same notification multiple times:
  • Retries — As mentioned above, if Metronome receives an error when attempting to deliver the notification to your webhook handler, we retry the notification. Depending on the nature of the error, it’s possible that your endpoint receives a notification without acknowledging it, in which case your endpoint receives the same notification again.
  • Multiple webhook URLs — If you configure Metronome to notify multiple webhook URLs, or even the same URL multiple times, notifications are sent multiple times. If you want to ensure duplicate notifications are ignored, you can use the notification’s id field to deduplicate.

​
Verify Notifications

Because your webhook endpoint is a public URL, anyone could send a request to it. Before you take actions based on the notification, you should verify the information it contains. You can do this in two ways: by fetching data from the Metronome API yourself or by verifying the webhook request’s signature.

​
Call the Metronome API

Webhook notifications contain only minimal information about the event that occurred. This means it’s often useful to call the appropriate Metronome API endpoint to get the full details. For example, if you receive a webhook notification informing you that an invoice has been finalized, you can call the /customers/{customer_id}/invoices/{invoice_id} endpoint to fetch the details of the invoice mentioned in the notification. In this way, the notification serves as a hint that something has changed, but your code relies only on data obtained directly from the Metronome API.

​
Verify Signatures

If the above strategy doesn’t work for your use case, Metronome also provides a method to verify the authenticity of notifications as you receive them by using the Metronome-Webhook-Signature HTTP header. The value of this header is a cryptographic signature of the HTTP request, using a secret key set up when you configure your webhook.
Secret keys are unique per webhookIf you have multiple webhooks configured on your Metronome account, each webhook has its own secret key.
To validate the signature, first concatenate the value of the request’s Date header and the exact bytes of the request body, separated by a newline character (\n). Then compute the HMAC-SHA256 of the resulting string, keyed by the webhook’s secret key. Finally, compare the hexadecimal representation of the HMAC you computed with the one found in the Metronome-Webhook-Signature header. If they don’t match, the webhook notification did not come from Metronome. 
HMAC_SHA256(secret_key, DATE_HEADER + "\n" + BODY)
The Date header is included to aid in deduplication. You should ignore webhook requests that are older than five minutes, which means your webhook handler only needs to store recent notification IDs to prevent duplicates.
THE BODY MUST BE TREATED AS BYTESWhen computing the signature, Metronome uses the exact bytes sent in the request body. Be careful to do the same in your code. If you try to use the parsed JSON body for verification purposes, you’ll likely fail signature verification because serializing the data again is not guaranteed to produce the same JSON.
The following code example shows how to perform signature validation: 
echo -n "$DATE_HEADER\n$BODY" | openssl dgst -sha256 -hmac $KEY
To test this, consider the following example webhook notification. The secret key for verification is 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  
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"  
  }  
}

​
Send Webhooks to Slack

If you want to receive Metronome alerts in Slack without building a custom webhook handler, you can configure Metronome to send notifications directly to a Slack channel. From there, you can triage and act on alerts. To send Metronome webhooks to Slack:
  1. Create an incoming webhook in Slack and copy the generated webhook URL. It’ll look something like: https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX
  2. Create a webhook destination in Metronome for your Slack channel. In the Metronome app, go to Connections > API tokens & webhooks > Webhooks > Add and paste your Slack webhook URL.
  3. Set up a test alert to verify the integration. In the Metronome app, go to Connections > Alerts > Create Alert and create an alert like Low credit balance reached.
  4. Verify the integration by testing the webhook connection. Trigger your test alert and check your Slack channel for a message from Metronome.
When properly configured, you’ll receive Slack messages that look like this: 
{  
  "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"  
}