Entitlement & Credit Trigger Webhooks

Entitlement and credit trigger webhooks fire based on your customers’ feature usage, not on data changes. They’re useful for notifying your team when customers are approaching or have hit a limit, and for surfacing in-app notifications to customers about their usage.

This page covers usage-based trigger events. For a full list of all webhook events, see Webhooks.

Entitlement trigger events

Entitlement triggers fire when a company’s usage for a specific feature crosses a threshold:

Event	When it fires
`entitlement.limit.reached`	Usage reaches the hard limit for a feature (100 percent of the allocation)
`entitlement.limit.warning`	Usage reaches 80 percent of the hard limit and is still below it
`entitlement.soft_limit.reached`	Usage reaches the soft limit for a feature
`entitlement.soft_limit.warning`	Usage reaches 80 percent of the soft limit and is still below it
`entitlement.tier_limit.reached`	Usage crosses a tier boundary of a tiered feature
`entitlement.tier_limit.warning`	Usage is 75 percent of the way through the current tier’s range

These percentages are fixed. They are not affected by a usage warning set on the entitlement, which is a value your app reads rather than a webhook trigger.

Each event fires once per feature per usage period. For trait-based features, which have no usage period, the event fires once per crossing and can fire again after usage falls back below the threshold.

Limit types explained:

Hard limit (limit) is the point at which access is restricted. For usage included with a plan, it represents that full usage amount. For pay as you go and overage pricing, it represents a (normally hidden) upper bound of usage you can configure, typically to prevent abuse or runaway spend.
Soft limit (soft_limit) applies to overage pricing and marks the point at which users start being billed for usage. You configure it, and Schematic components show it to the user.
Tier limit (tier_limit) applies to tiered pricing and fires as a company crosses into each successive pricing tier, letting you notify them of cost changes or prompt an upgrade.

Setup

Entitlement triggers must be configured per feature. When creating or updating a webhook endpoint in Schematic, add one or more entitlement trigger configs, each specifying the feature_id you want to monitor.

Payload

The body of each entitlement trigger webhook is typed as WebFeatureUsageWebhookOutput in the Node.js SDK:

Field	Description
`entitlement`	The entitlement ID that triggered the event
`feature`	Details about the feature being tracked
`company`	Details about the company whose usage triggered the event
`usage`	The company’s current usage count
`allocation`	The feature’s allocation (limit) for this company
`metricResetAt`	When the usage metric resets, if applicable

Common use cases

Internal alerts: Notify your team in Slack or your CRM when a customer hits a limit, so you can proactively reach out.
Customer-facing notifications: Trigger an in-app banner or email to customers when they’re nearing or over their limit.

Credit trigger events

Credit triggers fire based on credit usage:

Event	When it fires
`credit.limit.reached`	A company’s credit balance reaches the configured limit
`credit.limit.warning`	A company’s credit balance approaches the configured limit

Credit triggers are configured per credit type, using a credit_id in the trigger config when creating or updating a webhook endpoint.

Credit purchase events

This event fires when a company successfully purchases a credit bundle:

Event	When it fires
`credit.purchase.success`	A credit bundle purchase completes and the grants are committed

Payload

credit.purchase.success is typed as CreditsCreditPurchaseSuccess:

Field	Description
`bundleId`	ID of the purchased credit bundle
`bundleName`	Name of the purchased credit bundle
`company`	Summary of the purchasing company
`credit`	Summary of the credit that was topped up
`grantIds`	IDs of the credit grants created by the purchase
`quantity`	Number of credits granted by the purchase

Auto-topup events

These events fire on the outcome of a scheduled credit auto-topup:

Event	When it fires
`auto.topup.success`	An auto-topup completes and the credits are granted
`auto.topup.hard.failure`	An auto-topup attempt fails and will not be retried
`auto.topup.retry.exceeded`	An auto-topup has failed too many consecutive times

Payload

auto.topup.success is typed as CreditsAutoTopupSuccess:

Field	Description
`company`	Summary of the affected company
`credit`	Summary of the credit that was topped up
`grantId`	ID of the credit grant created by the top-up
`quantity`	Number of credits granted by the top-up

auto.topup.hard.failure is typed as CreditsAutoTopupHardFailure:

Field	Description
`company`	Summary of the affected company
`credit`	Summary of the credit that failed to top up
`errorMessage`	Human-readable error description
`stripeErrorCode`	Stripe error code, if the failure originated in Stripe

auto.topup.retry.exceeded is typed as CreditsAutoTopupRetryFailure:

Field	Description
`company`	Summary of the affected company
`credit`	Summary of the credit that failed to top up
`consecutiveFailures`	Number of consecutive failed attempts
`lastErrorMessage`	Human-readable description of the most recent error
`stripeErrorCode`	Stripe error code from the most recent attempt, if applicable

Common use cases

Internal alerts: Page your payments or ops team when a customer’s auto-topup is failing so you can reach out to update the payment method or remove access if you suspect abuse.
Customer-facing notifications: Send a billing failure email to the customer so they can update their payment method.