Usage Exceedance Webhooks

Get notified automatically when one of your customer organizations exceeds its subscribed usage limits. Scriptix delivers a webhook callback to your endpoint whenever a subscription goes over its Speech-to-Text or translation quota, so resellers can react to overages (top-up, upsell, throttle) without polling the usage APIs.

How It Works

Scriptix evaluates every active subscription once per hour. When usage in the current billing period exceeds a plan limit, a callback is sent to the webhook URL configured for that organization.

• Evaluated hourly against the current billing period.
• Fires only when usage is strictly greater than the limit (not on reaching it exactly).
• One notification per exceedance per billing period - you are not spammed every hour. A new notification is only sent again in the next billing period, or for a different limit type.
• Delivery is retried on the next hourly run until it succeeds (see Delivery & Retries).

Two limit types are monitored:

Type	Limit checked	Usage counted
stt	Plan Speech-to-Text limit	STT units plus alignment units used
translation	Plan translation character limit	Translation characters used

Only subscriptions that are active, started, not expired, and not suspended are evaluated.

Configuring the Webhook in the Portal

Exceedance webhooks are configured per customer organization from the back-office panel. Creating a webhook of type EXCEEDANCE_NOTIFICATION enables notifications for that organization; deleting it disables them - there is no separate on/off toggle.

note

Webhook configuration is available to back-office administrators.

Add a webhook

1. In the back-office sidebar, open Customers.
2. Select the customer organization you want to configure. This opens the customer overview.
3. Click the Webhooks card ("Configure customer webhook endpoints with HTTP methods, callback types, and custom headers"). The breadcrumb reads Customers › customer name › Webhooks.
4. Click Create (top-right) to open the Create new webhook dialog.
5. Fill in the form:
   • Webhook type - select EXCEEDANCE_NOTIFICATION.
   • Webhook URL - the endpoint that will receive callbacks (e.g. https://your-domain.com/webhook). HTTPS is strongly recommended.
   • HTTP method - POST (default) or PUT.
   • Custom headers (optional) - click + Add header to include headers such as Authorization: Bearer <token> for authenticating the callback.
6. Click Create. A "Webhook created successfully" confirmation appears, and the new webhook shows in the list with type EXCEEDANCE NOTIFICATION.

tip

The organization is set automatically from the customer you drilled into - there is no organization selector in the form.

Edit or remove a webhook

On the Webhooks list, use the row actions:

• Edit (pencil) - opens Update webhook to change the URL, method, or headers.
• Delete (trash) - removes the webhook and stops exceedance notifications for that organization.

Callback Payload

When an exceedance is detected, Scriptix sends the configured HTTP method (POST by default) with a JSON body:

{
  "event": "usage_exceedance",
  "organization_id": 456,
  "organization": "Acme Corp",
  "exceedances": [
    {
      "plan_sku": "PLAN-STT-PRO",
      "type": "stt",
      "limit": 1000000,
      "used": 1200000,
      "exceeded_by": 200000,
      "period_start": "2026-07-01",
      "period_end": "2026-08-01"
    }
  ]
}

Top-level fields

Field	Type	Description
event	string	Always usage_exceedance.
organization_id	number	ID of the organization that exceeded its limit.
organization	string	Organization name.
exceedances	array	One entry per subscription limit that is over (see below).

Exceedance entry

Field	Type	Description
plan_sku	string	SKU of the plan attached to the exceeding subscription.
type	string	stt or translation.
limit	number	The plan limit for this type.
used	number	Usage in the current billing period (STT includes alignment units).
exceeded_by	number	Amount over the limit (used - limit).
period_start	string	Current billing-period start (ISO date, YYYY-MM-DD).
period_end	string	Current billing-period end (ISO date, YYYY-MM-DD).

Headers

Custom headers from webhook_headers are sent as-is. Scriptix always sets User-Agent: Scriptix Speech to Text API. The body is JSON.

Delivery & Retries

• A delivery is considered successful when your endpoint responds with a 2XX status code within 30 seconds.
• On any non-2XX response, timeout, or connection error, the notification is not marked as sent and is retried on the next hourly run - until it succeeds or the billing period ends.
• Once delivered successfully, the exceedance is recorded and will not be re-sent for the same subscription, limit type, and billing period.
• Every attempt (success or failure) is recorded in the webhook delivery log for auditing.

Best Practices

• Respond fast, process async. Acknowledge with a 2XX immediately and handle the payload in the background to stay under the 30-second window.
• Secure your endpoint. Use the webhook_headers field to pass an authentication token and verify it on receipt.
• Handle repeats defensively. Although each exceedance is sent once per billing period on success, treat handlers as idempotent in case your endpoint returns a non-2XX after already processing the request.

Next Steps

• Usage & Reporting - Monitor usage across customers
• Subscriptions - Manage plans and limits
• Reseller Dashboard - Aggregate usage view