System notifications

System notifications monitor when events or actions occur based on the configured timestamp of an object (e.g contract start) or the time at which an action occurred (e.g. contract created). They’re best for time-based automation workflows around a customer’s key lifecycle events.

System notification types

PAYLOAD SCHEMA DIFFERENCESThe payload schema for system notifications differ slightly from the payload schema for threshold notifications. Specifically, the payload for system notifications do not include a properties field. Ensure your webhooks are properly configured to handle both notification types.

Type	Name	Details
Contract	`contract.create`	Triggers when a new contract is created
Contract	`contract.start`	Triggers when a contract is started
Contract	`contract.edit`	Triggers when a contract is edited. Adding or updating contract custom fields does not trigger this notification.
Contract	`contract.end`	Triggers when a contract ends
Contract	`contract.archive`	Triggers when a contract is archived
Commit & Credit	`commit.create`	Triggers when a new commit is created
Commit & Credit	`commit.edit`	Triggers when a commit is edited. Adding or updating commit custom fields does not trigger this notification.
Commit & Credit	`commit.archive`	Triggers when a commit is archived
Commit & Credit	`commit.segment.start`	Triggers when a commit segment starts The segment number that triggered the notification and the total number of commit segments can be found in the payload
Commit & Credit	`commit.segment.end`	Triggers when a commit segment ends The segment number that triggered the notification and the total number of commit segments can be found in the payload
Commit & Credit	`credit.create`	Triggers when a new credit is created
Commit & Credit	`credit.edit`	Triggers when a credit is edited. Adding or updating credit custom fields does not trigger this notification.
Commit & Credit	`credit.archive`	Triggers when a credit is archived
Commit & Credit	`credit.segment.start`	Triggers when a credit segment starts The segment number that triggered the notification and the total number of credit segments can be found in the payload
Commit & Credit	`credit.segment.end`	Triggers when a credit segment ends The segment number that triggered the notification and the total number of credit segments can be found in the payload
Subscription	`subscription.create`	Triggers when a new subscription is created on a contract
Subscription	`subscription.start`	Triggers when a subscription starts
Subscription	`subscription.end`	Triggers when a subscription ends
Rate card	`rate_card.create`	Triggers when a rate card is created
Rate card	`rate_card.edit`	Triggers when rate card metadata is edited For example, this notification triggers when you update the rate card name or rate card alias.
Rate card	`rate_card.archive`	Triggers when a rate card is archived
Rate card	`rate_card.rates_changed`	Triggers when one or more rates on a rate card change

Rate card notifications apply across your Metronome account and do not support offsets. The rate_card.rates_changed payload includes earliest_effective_at, the earliest effective time among the changed rates.

Webhook payload examples

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

{
  "id": "4dcef5c4-ed3b-5d0e-baa4-beec74544158",
  "type": "contract.start",
  "timestamp": "2025-08-07T00:00:00Z",
  "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"
  }
}

{
  "id": "ba0d43a2-9426-5219-9191-becdfb43e102",
  "type": "contract.edit",
  "timestamp": "2025-09-15T17:27:41Z",
  "environment_type": "PRODUCTION",
  "contract_id": "3b1cf6f5-e4ea-449f-acc3-afceffaddea7",
  "contract_custom_fields": {
    "org_key": "g_major"
  },
  "customer_id": "541be796-88fa-4081-8f8f-7ac230c43b2c",
  "customer_custom_fields": {
    "bill_customer_id": "0cu21JDIRIUDQKDS6wmx"
  }
}

{
  "id": "ba0d43a2-9426-5219-9191-becdfb43e102",
  "type": "contract.end",
  "timestamp": "2025-09-15T17:27:41Z",
  "environment_type": "PRODUCTION",
  "contract_id": "3b1cf6f5-e4ea-449f-acc3-afceffaddea7",
  "contract_custom_fields": {
    "org_key": "g_major"
  },
  "customer_id": "541be796-88fa-4081-8f8f-7ac230c43b2c",
  "customer_custom_fields": {
    "bill_customer_id": "0cu21JDIRIUDQKDS6wmx"
  }
}

{
  "id": "ba0d43a2-9426-5219-9191-becdfb43e102",
  "type": "contract.archive",
  "timestamp": "2025-09-15T17:27:41Z",
  "environment_type": "PRODUCTION",
  "contract_id": "3b1cf6f5-e4ea-449f-acc3-afceffaddea7",
  "contract_custom_fields": {
    "org_key": "g_major"
  },
  "customer_id": "541be796-88fa-4081-8f8f-7ac230c43b2c",
  "customer_custom_fields": {
    "bill_customer_id": "0cu21JDIRIUDQKDS6wmx"
  }
}

{
  "id": "23bbd69c-28bb-5f04-b609-ea716b0f00b4",
  "type": "commit.create",
  "timestamp": "2025-08-07T00:00:00Z",
  "environment_type": "PRODUCTION",
  "commit_id": "529a023b-3d3c-52b1-b6d5-4d3dd06c6cb0",
  "commit_custom_fields": {
    "tier_key": "f_minor"
  },
  "contract_id": "33d206f6-7455-49f6-857d-2172c37db68d",
  "contract_custom_fields": {
    "org_key": "g_major"
  },
  "parent_recurring_commit_id": "0719c77c-e3e1-4d1d-bb59-6cee63773f24",
  "customer_id": "1dd86915-97f1-4d92-8fa6-763c0235093a",
  "customer_custom_fields": {
    "bill_customer_id": "0cu21JDIRIUDQKDS6wmx"
  }
}

{
  "id": "33bbd69c-28bb-5f04-b609-ea716b0f00b4",
  "type": "commit.edit",
  "timestamp": "2025-08-07T00:00:00Z",
  "environment_type": "PRODUCTION",
  "commit_id": "529a023b-3d3c-52b1-b6d5-4d3dd06c6cb0",
  "commit_custom_fields": {
    "tier_key": "f_minor"
  },
  "contract_id": "33d206f6-7455-49f6-857d-2172c37db68d",
  "contract_custom_fields": {
    "org_key": "g_major"
  },
  "parent_recurring_commit_id": "0719c77c-e3e1-4d1d-bb59-6cee63773f24",
  "customer_id": "1dd86915-97f1-4d92-8fa6-763c0235093a",
  "customer_custom_fields": {
    "bill_customer_id": "0cu21JDIRIUDQKDS6wmx"
  }
}

{
  "id": "43bbd69c-28bb-5f04-b609-ea716b0f00b4",
  "type": "commit.archive",
  "timestamp": "2025-08-07T00:00:00Z",
  "environment_type": "PRODUCTION",
  "commit_id": "529a023b-3d3c-52b1-b6d5-4d3dd06c6cb0",
  "commit_custom_fields": {
    "tier_key": "f_minor"
  },
  "contract_id": "33d206f6-7455-49f6-857d-2172c37db68d",
  "contract_custom_fields": {
    "org_key": "g_major"
  },
  "parent_recurring_commit_id": "0719c77c-e3e1-4d1d-bb59-6cee63773f24",
  "customer_id": "1dd86915-97f1-4d92-8fa6-763c0235093a",
  "customer_custom_fields": {
    "bill_customer_id": "0cu21JDIRIUDQKDS6wmx"
  }
}

{
  "id": "92adc38c-671c-59dd-8f2e-39fc7482a4df",
  "type": "commit.segment.start",
  "timestamp": "2025-08-07T00:00:00Z",
  "environment_type": "PRODUCTION",
  "commit_id": "529a023b-3d3c-52b1-b6d5-4d3dd06c6cb0",
  "commit_custom_fields": {
    "tier_key": "f_minor"
  },
  "contract_id": "33d206f6-7455-49f6-857d-2172c37db68d",
  "contract_custom_fields": {
    "org_key": "g_major"
  },
  "parent_recurring_commit_id": "0718c77c-e3e1-4d1d-bb59-6cee63773f24",
  "segment_index": 0,
  "segment_count": 1,
  "segment_id": "dea59112-dadb-52c4-8789-304e2cddff92",
  "customer_id": "1ed86915-97f1-4d92-8fa6-763c0235093a",
  "customer_custom_fields": {
    "bill_customer_id": "0cu21JDIRIUDQKDS6wmx"
  }
}

{
  "id": "a2adc38c-671c-59dd-8f2e-39fc7482a4df",
  "type": "commit.segment.end",
  "timestamp": "2025-08-07T00:00:00Z",
  "environment_type": "PRODUCTION",
  "commit_id": "529a023b-3d3c-52b1-b6d5-4d3dd06c6cb0",
  "commit_custom_fields": {
    "tier_key": "f_minor"
  },
  "contract_id": "33d206f6-7455-49f6-857d-2172c37db68d",
  "contract_custom_fields": {
    "org_key": "g_major"
  },
  "parent_recurring_commit_id": "0718c77c-e3e1-4d1d-bb59-6cee63773f24",
  "segment_index": 0,
  "segment_count": 1,
  "segment_id": "dea59112-dadb-52c4-8789-304e2cddff92",
  "customer_id": "1ed86915-97f1-4d92-8fa6-763c0235093a",
  "customer_custom_fields": {
    "bill_customer_id": "0cu21JDIRIUDQKDS6wmx"
  }
}

{
  "id": "23bbd69c-28bb-5f04-b609-ea716b0f00b4",
  "type": "credit.create",
  "timestamp": "2025-08-07T00:00:00Z",
  "environment_type": "PRODUCTION",
  "credit_id": "529a023b-3d3c-52b1-b6d5-4d3dd06c6cb0",
  "credit_custom_fields": {
    "tier_key": "f_minor"
  },
  "contract_id": "33d206f6-7455-49f6-857d-2172c37db68d",
  "contract_custom_fields": {
    "org_key": "g_major"
  },
  "parent_recurring_credit_id": "0719c77c-e3e1-4d1d-bb59-6cee63773f24",
  "customer_id": "1dd86915-97f1-4d92-8fa6-763c0235093a",
  "customer_custom_fields": {
    "bill_customer_id": "0cu21JDIRIUDQKDS6wmx"
  }
}

{
  "id": "33bbd69c-28bb-5f04-b609-ea716b0f00b4",
  "type": "credit.edit",
  "timestamp": "2025-08-07T00:00:00Z",
  "environment_type": "PRODUCTION",
  "credit_id": "529a023b-3d3c-52b1-b6d5-4d3dd06c6cb0",
  "credit_custom_fields": {
    "tier_key": "f_minor"
  },
  "contract_id": "33d206f6-7455-49f6-857d-2172c37db68d",
  "contract_custom_fields": {
    "org_key": "g_major"
  },
  "parent_recurring_credit_id": "0719c77c-e3e1-4d1d-bb59-6cee63773f24",
  "customer_id": "1dd86915-97f1-4d92-8fa6-763c0235093a",
  "customer_custom_fields": {
    "bill_customer_id": "0cu21JDIRIUDQKDS6wmx"
  }
}

{
  "id": "43bbd69c-28bb-5f04-b609-ea716b0f00b4",
  "type": "credit.archive",
  "timestamp": "2025-08-07T00:00:00Z",
  "environment_type": "PRODUCTION",
  "credit_id": "529a023b-3d3c-52b1-b6d5-4d3dd06c6cb0",
  "credit_custom_fields": {
    "tier_key": "f_minor"
  },
  "contract_id": "33d206f6-7455-49f6-857d-2172c37db68d",
  "contract_custom_fields": {
    "org_key": "g_major"
  },
  "parent_recurring_credit_id": "0719c77c-e3e1-4d1d-bb59-6cee63773f24",
  "customer_id": "1dd86915-97f1-4d92-8fa6-763c0235093a",
  "customer_custom_fields": {
    "bill_customer_id": "0cu21JDIRIUDQKDS6wmx"
  }
}

{
  "id": "92adc38c-671c-59dd-8f2e-39fc7482a4df",
  "type": "credit.segment.start",
  "timestamp": "2025-08-07T00:00:00Z",
  "environment_type": "PRODUCTION",
  "credit_id": "529a023b-3d3c-52b1-b6d5-4d3dd06c6cb0",
  "credit_custom_fields": {
    "tier_key": "f_minor"
  },
  "contract_id": "33d206f6-7455-49f6-857d-2172c37db68d",
  "contract_custom_fields": {
    "org_key": "g_major"
  },
  "parent_recurring_credit_id": "0718c77c-e3e1-4d1d-bb59-6cee63773f24",
  "segment_index": 0,
  "segment_count": 1,
  "segment_id": "dea59112-dadb-52c4-8789-304e2cddff92",
  "customer_id": "1ed86915-97f1-4d92-8fa6-763c0235093a",
  "customer_custom_fields": {
    "bill_customer_id": "0cu21JDIRIUDQKDS6wmx"
  }
}

{
  "id": "a2adc38c-671c-59dd-8f2e-39fc7482a4df",
  "type": "credit.segment.end",
  "timestamp": "2025-08-07T00:00:00Z",
  "environment_type": "PRODUCTION",
  "credit_id": "529a023b-3d3c-52b1-b6d5-4d3dd06c6cb0",
  "credit_custom_fields": {
    "tier_key": "f_minor"
  },
  "contract_id": "33d206f6-7455-49f6-857d-2172c37db68d",
  "contract_custom_fields": {
    "org_key": "g_major"
  },
  "parent_recurring_credit_id": "0718c77c-e3e1-4d1d-bb59-6cee63773f24",
  "segment_index": 0,
  "segment_count": 1,
  "segment_id": "dea59112-dadb-52c4-8789-304e2cddff92",
  "customer_id": "1ed86915-97f1-4d92-8fa6-763c0235093a",
  "customer_custom_fields": {
    "bill_customer_id": "0cu21JDIRIUDQKDS6wmx"
  }
}

{
  "id": "b7e2f1a4-3c5d-5e6f-8a9b-0c1d2e3f4a5b",
  "type": "subscription.create",
  "timestamp": "2026-10-01T15:30:00Z",
  "environment_type": "PRODUCTION",
  "subscription_id": "6a1f8c3e-2b4d-4e5f-9a7b-8c9d0e1f2a3b",
  "subscription_custom_fields": {
    "seat_type": "developer"
  },
  "starting_at": "2026-11-01T00:00:00Z",
  "ending_before": null,
  "payment_gate_config": {
    "payment_gate_type": "STRIPE",
    "tax_type": "STRIPE"
  },
  "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"
  }
}

{
  "id": "c8f3a2b5-4d6e-5f7a-9b0c-1d2e3f4a5b6c",
  "type": "subscription.start",
  "timestamp": "2026-11-01T00:00:00Z",
  "environment_type": "PRODUCTION",
  "subscription_id": "6a1f8c3e-2b4d-4e5f-9a7b-8c9d0e1f2a3b",
  "subscription_custom_fields": {
    "seat_type": "developer"
  },
  "starting_at": "2026-11-01T00:00:00Z",
  "payment_gate_config": {
    "payment_gate_type": "STRIPE",
    "tax_type": "STRIPE"
  },
  "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"
  }
}

{
  "id": "d9a4b3c6-5e7f-5a8b-9c1d-2e3f4a5b6c7d",
  "type": "subscription.end",
  "timestamp": "2027-01-01T00:00:00Z",
  "environment_type": "PRODUCTION",
  "subscription_id": "7b2a9d4f-3c5e-4f6a-8b9c-0d1e2f3a4b5c",
  "subscription_custom_fields": {
    "seat_type": "admin"
  },
  "ending_before": "2027-01-01T00:00:00Z",
  "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"
  }
}

{
  "id": "4d7f6d2a-f149-4a89-9917-4f4cb29ca198",
  "type": "rate_card.create",
  "timestamp": "2026-09-16T19:30:00Z",
  "environment_type": "PRODUCTION",
  "rate_card_id": "2c7c7f4b-63ac-43bf-8c42-676298471cea",
  "custom_fields": {
    "rate_card_type": "standard"
  }
}

{
  "id": "5e8a7e3b-a250-4b9a-a228-5f5dc3ad9b29",
  "type": "rate_card.edit",
  "timestamp": "2026-09-16T19:35:00Z",
  "environment_type": "PRODUCTION",
  "rate_card_id": "2c7c7f4b-63ac-43bf-8c42-676298471cea",
  "custom_fields": {
    "rate_card_type": "standard"
  }
}

{
  "id": "6f9b8f4c-b361-4cab-b339-6f6ed4bea13a",
  "type": "rate_card.archive",
  "timestamp": "2026-09-16T19:40:00Z",
  "environment_type": "PRODUCTION",
  "rate_card_id": "2c7c7f4b-63ac-43bf-8c42-676298471cea",
  "custom_fields": {
    "rate_card_type": "standard"
  }
}

{
  "id": "91ab4d1c-5962-4252-a21d-dab9e88868ee",
  "type": "rate_card.rates_changed",
  "timestamp": "2026-09-16T19:45:00Z",
  "environment_type": "PRODUCTION",
  "rate_card_id": "2c7c7f4b-63ac-43bf-8c42-676298471cea",
  "custom_fields": {
    "rate_card_type": "standard"
  },
  "earliest_effective_at": "2026-10-01T00:00:00Z"
}

Enabling and managing system notifications

System notifications can be enabled and managed through both the UI and the API.

Notifications list interface showing various notification types and their status

In the UI

Navigate to the Notifications tab
Find the system notification that you’d like to enable. All available system notifications will appear in the notifications list view and be disabled by default for any account
Click on the notification
Click the toggle next to Status to enable
Confirm action to enable
You will begin receiving notifications about this system event for all customers to all configured webhooks
Ensure your webhooks are set up to properly handle the payloads for these notifications

Via API

Call POST /v2/notifications/edit
Pass a policy object with the type of the system notification and is_enabled set to true. Omit id, which applies only to offset notifications
{ "policy": { "type": "contract.create" }, "is_enabled": true }

A successful response will return a 200 response code

{
  "data": {
    "type": "SYSTEM_LIFECYCLE_EVENT",
    "is_enabled": true,
    "policy": { "type": "contract.create" }
  }
}

HISTORICAL DATA LIMITATIONWhen you enable a system notification, Metronome starts generating events from that point forward. It does not go back and create events for past data. Additionally, the policy for system notifications cannot be edited.

GET STARTED

IMPLEMENT METRONOME

EVENTS

PRICING & PACKAGING

CUSTOMERS & BILLING

INVOICING

REPORTING & INSIGHTS

PLATFORM CONFIGURATION

System notifications

System notification types

Webhook payload examples

Enabling and managing system notifications

​System notification types

​Webhook payload examples

​Enabling and managing system notifications

System notification types

Webhook payload examples

Enabling and managing system notifications