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.

Entitlement trigger events

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

Limit types explained:

• Hard limit (limit) — the point at which access is restricted. For usage included with a plan, this represents that full usage amount. For pay as you go and overage pricing, this represents a (normally hidden) upper bound of usage you can configure, typically to prevent abuse or runaway spend.
• Soft limit (soft_limit) — For overage pricing, represents the point at which users will start being billed for usage. This is configurable and shown to the user in Schematic components.
• Tier limit (tier_limit) — For tiered pricing, 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:

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:

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

Auto-topup failure events

These events fire when a scheduled credit auto-topup fails:

Payload

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

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

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.