Webhook Events

This page documents all webhook events and their payload structures.

Available Events

Invoice Events

Event	Description
`invoice.created`	Fired when a new invoice is created
`invoice.updated`	Fired when an invoice is updated (status change, payment, void)

Contract Events

Event	Description
`contract.created`	Fired when a new contract is created
`contract.updated`	Fired when a contract is modified
`contract.terminated`	Fired when a contract is terminated or cancelled

Customer Events

Event	Description
`customer.created`	Fired when a new customer is created
`customer.updated`	Fired when a customer is modified

Credit Events

Event	Description
`credit.threshold_crossed`	Fired when balance drops below a configured threshold
`credit.balance_depleted`	Fired when a credit wallet balance reaches zero
`credit.budget.exhausted`	Fired when a budget spending cap is fully consumed

Event Payloads

All webhook payloads follow this structure:

{
  "id": "string",
  // ... event-specific fields
  "createdAt": "ISO 8601 timestamp",
  "updatedAt": "ISO 8601 timestamp"
}

Invoice Events

invoice.created

Fired when a new invoice is created.

When it’s triggered

Invoice is manually created in the dashboard
Invoice is created via API
Invoice is auto-generated by a rolling contract

Payload

string

Invoice UUID

invoiceNum

string

Human-readable invoice number (e.g., “INV-001”)

status

string

Invoice status: Drafted, In Progress, In Transit, Paid, Cancelled, Refunded

totalCents

integer

Total amount in cents (e.g., 10000 = $100.00)

invoiceDate

string

Invoice date in YYYY-MM-DD format

dueDate

string

Payment due date in YYYY-MM-DD format

memo

string | null

Optional memo or notes on the invoice

paymentLink

string | null

URL to the payment portal where customer can pay (expires after 90 days)

customer

object

Customer information

Show Customer object

customer.id

string

Customer UUID

customer.name

string

Customer display name

customer.legalName

string | null

Customer legal name

customer.externalIds

string[]

External company IDs from your systems (e.g., CRM, ERP). Only present if configured.

createdAt

string

ISO 8601 timestamp when invoice was created

updatedAt

string

ISO 8601 timestamp when invoice was last updated

Example Payload

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "invoiceNum": "INV-001",
  "status": "In Progress",
  "totalCents": 150000,
  "invoiceDate": "2026-01-15",
  "dueDate": "2026-02-14",
  "memo": "Q1 2026 services",
  "paymentLink": "https://app.monk.com/pay/eyJhbGciOiJIUzI1NiIs...",
  "customer": {
    "id": "cust-uuid-1234",
    "name": "Acme Corp",
    "legalName": "Acme Corporation Inc.",
    "externalIds": ["salesforce-001", "netsuite-12345"]
  },
  "createdAt": "2026-01-15T10:30:00.000Z",
  "updatedAt": "2026-01-15T10:30:00.000Z"
}

invoice.updated

Fired when an invoice is modified.

When it’s triggered

Invoice status changes (e.g., In Progress → Paid)
Invoice is cancelled or refunded
Invoice fields are updated
Payment is applied to invoice

Payload

The payload structure is identical to invoice.created. The status field reflects the new invoice state.

Example Payload (Invoice Paid)

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "invoiceNum": "INV-001",
  "status": "Paid",
  "totalCents": 150000,
  "invoiceDate": "2026-01-15",
  "dueDate": "2026-02-14",
  "memo": "Q1 2026 services",
  "paymentLink": null,
  "customer": {
    "id": "cust-uuid-1234",
    "name": "Acme Corp",
    "legalName": "Acme Corporation Inc.",
    "externalIds": ["salesforce-001"]
  },
  "createdAt": "2026-01-15T10:30:00.000Z",
  "updatedAt": "2026-01-20T14:22:00.000Z"
}

Contract Events

contract.created

Fired when a new contract is created.

When it’s triggered

Contract is created from a plan via API
Contract is created from a plan in the dashboard
Contract is created via integrations (e.g., Stripe sync)

Payload

string

Contract UUID

name

string | null

Contract name

startDate

string | null

Contract start date in YYYY-MM-DD format

endDate

string | null

Contract end date in YYYY-MM-DD format. Null for month-to-month contracts.

isActive

boolean

Whether the contract is currently active

autoPayEnabled

boolean

Whether auto-pay is enabled for this contract

customer

object

Customer information

Show Customer object

customer.id

string

Customer UUID

customer.name

string

Customer display name

customer.legalName

string | null

Customer legal name

createdAt

string

ISO 8601 timestamp when contract was created

updatedAt

string

ISO 8601 timestamp when contract was last updated

Example Payload

{
  "id": "contract-uuid-1234",
  "name": "Enterprise Annual Plan",
  "startDate": "2026-01-01",
  "endDate": "2027-01-01",
  "isActive": true,
  "autoPayEnabled": true,
  "customer": {
    "id": "cust-uuid-1234",
    "name": "Acme Corp",
    "legalName": "Acme Corporation Inc."
  },
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z"
}

contract.updated

Fired when a contract is modified.

When it’s triggered

Contract fields are updated
Auto-pay is enabled or disabled
Contract dates are modified

Payload

The payload structure is identical to contract.created.

Example Payload

{
  "id": "contract-uuid-1234",
  "name": "Enterprise Annual Plan",
  "startDate": "2026-01-01",
  "endDate": "2027-01-01",
  "isActive": true,
  "autoPayEnabled": false,
  "customer": {
    "id": "cust-uuid-1234",
    "name": "Acme Corp",
    "legalName": "Acme Corporation Inc."
  },
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-02-15T10:30:00.000Z"
}

contract.terminated

Fired when a contract is terminated or cancelled.

When it’s triggered

Contract is cancelled via API
Contract is terminated in the dashboard
Subscription is cancelled at end of billing period

Payload

The payload structure is identical to contract.created. The isActive field will be false.

Example Payload

{
  "id": "contract-uuid-1234",
  "name": "Enterprise Annual Plan",
  "startDate": "2026-01-01",
  "endDate": "2026-06-15",
  "isActive": false,
  "autoPayEnabled": false,
  "customer": {
    "id": "cust-uuid-1234",
    "name": "Acme Corp",
    "legalName": "Acme Corporation Inc."
  },
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-06-15T14:00:00.000Z"
}

Customer Events

customer.created

Fired when a new customer is created.

When it’s triggered

Customer is created via API
Customer is created in the dashboard
Customer is created via integrations

Payload

string

Customer UUID

publicId

string

Public-facing customer ID (e.g., “cus_Hk7Lm9Np3Qr5Tv8X”)

name

string

Customer display name

legalName

string | null

Customer legal name

Example Payload

{
  "id": "cust-uuid-1234",
  "publicId": "cus_Hk7Lm9Np3Qr5Tv8X",
  "name": "Acme Corp",
  "legalName": "Acme Corporation Inc.",
  "tags": ["enterprise", "annual"],
  "createdAt": "2026-01-15T10:30:00.000Z",
  "updatedAt": "2026-01-15T10:30:00.000Z"
}

customer.updated

Fired when a customer is modified.

When it’s triggered

Customer fields are updated via API
Customer is updated in the dashboard
Customer tags are modified

Payload

The payload structure is identical to customer.created.

Example Payload

{
  "id": "cust-uuid-1234",
  "publicId": "cus_Hk7Lm9Np3Qr5Tv8X",
  "name": "Acme Corporation",
  "legalName": "Acme Corporation Inc.",
  "tags": ["enterprise", "annual", "priority"],
  "createdAt": "2026-01-15T10:30:00.000Z",
  "updatedAt": "2026-02-20T09:15:00.000Z"
}

Credit Events

credit.threshold_crossed

Fired when a credit wallet balance drops below a configured alert threshold.

When it’s triggered

Usage deductions cause the balance to fall below a threshold percentage of the High-Water Mark
Each threshold only fires once until the balance recovers past it (partial reset)

Thresholds are calculated as a percentage of the High-Water Mark (HWM) — the maximum balance ever reached in the wallet. This auto-scales with customer growth. Default thresholds are 25%, 10%, and 0%.

Use this event to trigger proactive workflows like alerting your team before credits run out, notifying the customer to top up, or automatically granting additional credits.

Payload

contractId

string

Contract UUID associated with the credit wallet

customerId

string

Customer UUID

customerName

string

Customer display name

threshold

number

The threshold that was crossed, as a decimal (e.g., 0.25 = 25%)

currentBalanceCents

integer

Current wallet balance in cents

highWaterMarkCents

integer

High-Water Mark (maximum balance ever reached) in cents

percentRemaining

number

Current balance as a percentage of HWM (e.g., 0.08 = 8%)

crossedAt

string

ISO 8601 timestamp when the threshold was crossed

Example Payload

{
  "contractId": "contract-uuid-1234",
  "customerId": "cust-uuid-5678",
  "customerName": "Acme Corp",
  "threshold": 0.25,
  "currentBalanceCents": 200000,
  "highWaterMarkCents": 1000000,
  "percentRemaining": 0.2,
  "crossedAt": "2026-03-01T14:30:00.000Z"
}

credit.balance_depleted

Fired when a credit wallet balance reaches zero. This is a special case of credit.threshold_crossed with threshold: 0.

When it’s triggered

Usage deductions consume the remaining credit balance
The wallet balance reaches exactly zero

Credit balances are updated in near-real-time as part of usage aggregation. There is minimal delay between when usage depletes the wallet and when this webhook fires.

Use this event to trigger automated workflows like notifying your team to top up credits, pausing service access, or alerting the customer.

Payload

contractId

string

Contract UUID associated with the credit wallet

customerId

string

Customer UUID

customerName

string

Customer display name

highWaterMarkCents

integer

High-Water Mark (maximum balance ever reached) in cents

depletedAt

string

ISO 8601 timestamp when the wallet was depleted

Example Payload

{
  "contractId": "contract-uuid-1234",
  "customerId": "cust-uuid-5678",
  "customerName": "Acme Corp",
  "highWaterMarkCents": 100000,
  "depletedAt": "2026-03-01T14:30:00.000Z"
}

credit.budget.exhausted

Fired when a credit budget’s spending cap is fully consumed. Credit budgets let you set per-dimension spending limits on shared credit pools — for example, capping how much each brand or team can consume from a shared wallet.

When it’s triggered

Usage deductions cause a dimension’s cumulative spend to reach or exceed its configured budget cap
The dimension is identified by an event property key/value pair (e.g., brand=Dove)
Each budget fires this event only once — it will not re-fire on subsequent refreshes

Budget usage is computed from ClickHouse event data during each usage refresh cycle. There may be a brief delay between when usage occurs and when the budget check runs.

Use this event to pause service for a specific dimension at your API gateway, notify stakeholders, or trigger automated workflows.

Payload

contractId

string

Contract UUID associated with the credit wallet

customerId

string

Customer UUID

customerName

string

Customer display name

budgetLabel

string

Human-readable label for the budget (e.g., “Dove”)

eventPropertyKey

string

The event property key used to partition usage (e.g., “brand”)

eventPropertyValue

string

The specific dimension value this budget tracks (e.g., “Dove”)

meterId

string | null

Meter ID if budget is scoped to a specific credit type. Null if budget applies to all meters.

maxCreditsCents

integer

The budget spending cap in cents

maxCredits

number | null

The budget spending cap in credit units. Null for dollar-only wallets.

consumedCents

integer

Total credits consumed by this dimension in cents

consumedCredits

number | null

Total credits consumed in credit units. Null for dollar-only wallets.

exhaustedAt

string

ISO 8601 timestamp when the budget was exhausted

Example Payload

{
  "contractId": "contract-uuid-1234",
  "customerId": "cust-uuid-5678",
  "customerName": "Unilever",
  "budgetLabel": "Dove",
  "eventPropertyKey": "brand",
  "eventPropertyValue": "Dove",
  "meterId": null,
  "maxCreditsCents": 500000,
  "maxCredits": 1000,
  "consumedCents": 512300,
  "consumedCredits": 1024.6,
  "exhaustedAt": "2026-04-01T14:30:00.000Z"
}

Reference

Invoice Status Values

Status	Description
`Drafted`	Invoice is being prepared, not yet finalized
`In Progress`	Invoice is finalized and ready for payment
`In Transit`	Payment initiated, awaiting reconciliation
`Paid`	Invoice has been fully paid
`Cancelled`	Invoice has been cancelled
`Refunded`	Invoice has been refunded

Get Started

Core Concepts

Webhooks

Documentation Index

​Webhook Events

​Available Events

​Invoice Events

​Contract Events

​Customer Events

​Credit Events

​Event Payloads

​Invoice Events

​invoice.created

​When it’s triggered

​Payload

​Example Payload

​invoice.updated

​When it’s triggered

​Payload

​Example Payload (Invoice Paid)

​Contract Events

​contract.created

​When it’s triggered

​Payload

​Example Payload

​contract.updated

​When it’s triggered

​Payload

​Example Payload

​contract.terminated

​When it’s triggered

​Payload

​Example Payload

​Customer Events

​customer.created

​When it’s triggered

​Payload

​Example Payload

​customer.updated

​When it’s triggered

​Payload

​Example Payload

​Credit Events

​credit.threshold_crossed

​When it’s triggered

​Payload

​Example Payload

​credit.balance_depleted

​When it’s triggered

​Payload

​Example Payload

​credit.budget.exhausted

​When it’s triggered

​Payload

​Example Payload

​Reference

​Invoice Status Values

Webhook Events

Available Events

Invoice Events

Contract Events

Customer Events

Credit Events

Event Payloads

Invoice Events

invoice.created

When it’s triggered

Payload

Example Payload

invoice.updated

When it’s triggered

Payload

Example Payload (Invoice Paid)

Contract Events

contract.created

When it’s triggered

Payload

Example Payload

contract.updated

When it’s triggered

Payload

Example Payload

contract.terminated

When it’s triggered

Payload

Example Payload

Customer Events

customer.created

When it’s triggered

Payload

Example Payload

customer.updated

When it’s triggered

Payload

Example Payload

Credit Events

credit.threshold_crossed

When it’s triggered

Payload

Example Payload

credit.balance_depleted

When it’s triggered

Payload

Example Payload

credit.budget.exhausted

When it’s triggered

Payload

Example Payload

Reference

Invoice Status Values