Skip to main content
Webhooks allow you to keep downstream systems in sync by streaming real-time credit events. Each webhook payload provides enough context to understand what happened and to reconcile it against your own systems.

​
Events

​
Grant-level events

  • credits.granted — A new credits grant (block) was created.
  • credits.grant.updated — An existing credits grant changed (e.g., amount, dates, cost).
  • credits.grant.usage_low — A specific grant crossed one of the configured low-credits thresholds. Thresholds are configurable, allowing multiple alert levels.
  • credits.grant.depleted — A specific grant’s balance reached zero.
  • credits.expired — A grant reached its expiration time.

​
Balance-level events

  • credits.balance.usage_low — Aggregate balance (per customer/resource/currency) fell below one of the configured thresholds. Thresholds are configurable per customer, allowing multiple alert levels (e.g., 80%, 50%, 20%).
  • credits.balance.depleted — Aggregate balance (per customer/resource/currency) reached zero.

​
Credit consumption

FieldData type (typical)Notes
environment_idstring/uuidEnvironment identifier
customer_idstring/uuidCustomer identifier
resource_idstring/uuidResource identifier
event_idstring/uuidUsage event identifier
feature_idstring/uuidMetered feature identifier
partial_costdecimalPortion of cost attributed to a specific grant/block
total_costdecimalTotal cost of the event across all grants/blocks
credit_grant_idstring/uuidReference to the credit grant used
credit_currency_idstring/uuidCredit currency identifier
consumption_timestamptimestampWhen consumption was recorded
event_timestamptimestampWhen the underlying event occurred
created_attimestampIngestion/row creation time

​
Credit grants

FieldData type (typical)Notes
idstring/uuidPrimary identifier of the credit grant
created_attimestampRow creation time
updated_attimestampLast update time
account_idstring/uuidAccount identifier
environment_idstring/uuidEnvironment identifier
display_namestringHuman-readable name/label
amountdecimalGranted credits amount
consumed_amountdecimalCredits consumed from this grant
grant_typestring/enumGrant category/type (e.g., promo, purchase)
priorityintegerConsumption priority among grants
effective_attimestampWhen the grant becomes usable
expire_attimestampWhen the grant expires
additional_meta_datajsonArbitrary metadata
commentstringOptional note/comment
customer_idstring/uuidCustomer identifier
customer_ref_idstringExternal/customer reference ID
resource_idstring/uuidResource identifier
resource_ref_idstringExternal/resource reference ID
custom_currency_idstring/uuidReference to custom currency (if applicable)
currency_idstring/uuidReference to base currency
cost_amountdecimalMonetary cost amount (if tracked)
cost_currencystringISO currency code for cost_amount
credit_grant_idstring/uuidGrant identifier (if separate from id)

​
Custom currencies

FieldData type (typical)Notes
idstring/uuidPrimary identifier
created_attimestampRow creation time
updated_attimestampLast update time
account_idstring/uuidAccount identifier
environment_idstring/uuidEnvironment identifier
display_namestringCurrency display name
currency_idstring/uuidBase currency reference
symbolstringDisplay symbol (e.g., “AIT”)
descriptionstringOptional description
additional_meta_datajsonArbitrary metadata
units_singularstringSingular unit label (e.g., “AI Token”)
units_pluralstringPlural unit label (e.g., “AI Tokens”)

​
Notifying customers about low balance and depletion

Use credit webhooks to proactively notify customers before they run out of credits and when their balance is depleted. This helps prevent unexpected service interruptions and improves customer experience.

​
Setting up configurable thresholds

Thresholds are configurable per customer, allowing you to set multiple alert levels (e.g., 80%, 50%, 20% remaining). When a customer’s credit balance crosses any of these thresholds, Stigg fires a credits.balance.usage_low webhook event.
ThresholdRecommended action
80% remainingSend a gentle reminder email or in-app notification that credits are being consumed
50% remainingDisplay a more prominent in-app banner suggesting the customer top up soon
20% remainingSend an urgent notification and consider enabling auto top-up prompts
0% remaining (depleted)Notify the customer their credits are exhausted and prompt immediate action

​
Implementation example

// Webhook handler for credit balance events
app.post('/webhooks/stigg', async (req, res) => {
  const event = req.body;

  switch (event.type) {
    case 'credit_balance.low':
      const { customer, creditCurrency, remainingBalancePercentage, thresholdPercentage } = event;

      // Send notification based on threshold
      if (thresholdPercentage <= 20) {
        await sendUrgentLowBalanceEmail(customer, creditCurrency, remainingBalancePercentage);
      } else if (thresholdPercentage <= 50) {
        await showInAppBanner(customer.id, 'Your credits are running low. Consider topping up.');
      } else {
        await sendLowBalanceReminder(customer, creditCurrency);
      }
      break;

    case 'credit_balance.depleted':
      const { customer: depletedCustomer, creditCurrency: depletedCurrency } = event;

      // Notify customer and optionally restrict access
      await sendDepletionNotification(depletedCustomer, depletedCurrency);
      await promptTopUp(depletedCustomer.id);
      break;
  }

  res.status(200).send('OK');
});

​
Use cases

  • Email notifications — Send automated emails at each threshold to keep customers informed
  • In-app banners — Display contextual warnings in your application UI
  • Slack/Teams alerts — Notify customer success teams when high-value customers are running low
  • Auto top-up triggers — Prompt customers to enable automatic recharging before they deplete
  • Usage dashboards — Update real-time dashboards showing credit consumption trends
  • Access enforcement — Implement hard or soft limits when credits are depleted

​
Best practices

  1. Use idempotency — The messageId field ensures you don’t process the same event twice
  2. Configure multiple thresholds — Set alerts at 80%, 50%, and 20% to give customers time to act
  3. Personalize messaging — Include the credit currency name and remaining balance in notifications
  4. Provide clear CTAs — Always include a direct link to top up or manage credits
  5. Track engagement — Monitor which notifications drive the most top-ups to optimize your strategy