Messaging Quota Near Full

Triggered when the messaging quota for a workspace reaches or exceeds 90% utilization within the current billing period.

WEBHOOK workspace:quota_near_full:messaging

Example Request Body

{
  "workspace_id": "my-workspace",
  "event_type": "workspace:quota_full:messaging",
  "partner_id": "partner_12345",
  "triggered_at": "2024-01-01T12:00:00.000Z",
  "messaging_quota_total": 100000,
  "messaging_quota_used": 90000,
  "current_period_start": "2024-01-01T00:00:00.000Z",
  "current_period_end": "2024-01-31T23:59:59.000Z",
  "utilization_pct": 90
}

Headers

X-TL-Partner-Id · string · required

The unique identifier for the partner.

X-TL-Signature · string · required

A JSON Web Token (JWT) signed with your Partner Secret using the HS256 algorithm. Use this header to verify that the webhook was genuinely sent by TimelinesAI.

The JWT contains the following claims: | Claim | Description | |-------|-------------| | partner_id | Your partner identifier — must match the X-TL-Partner-Id header | | nbf | Not-before timestamp (Unix epoch) | | exp | Expiration timestamp (Unix epoch) |

Verification steps:

1. Extract the X-TL-Signature header value from the incoming request.
2. Decode and verify the JWT using your Partner Secret with the HS256 algorithm.
3. Confirm that the partner_id claim matches the X-TL-Partner-Id header.
4. Reject the request if verification fails (invalid signature, expired token, or mismatched partner ID).

JavaScript example:

const jwt = require(''jsonwebtoken'');
function verifyWebhook(req) {
  const signature = req.headers[''x-tl-signature''];
  const partnerId = req.headers[''x-tl-partner-id''];
  try {
    const decoded = jwt.verify(signature, PARTNER_SECRET);
    return decoded.partner_id === partnerId;
  } catch (err) {
    return false;
  }
}

Python example:

import jwt
def verify_webhook(headers):
    signature = headers.get(''X-TL-Signature'')
    partner_id = headers.get(''X-TL-Partner-Id'')
    try:
        decoded = jwt.decode(signature, PARTNER_SECRET, algorithms=[''HS256''])
        return decoded[''partner_id''] == partner_id
    except jwt.InvalidTokenError:
        return False

See the PartnerAPI Webhooks Overview for more details.

Body

application/json

Webhook payload sent when the messaging quota for a workspace reaches or exceeds 90 or 100 percent utilization within the current billing period.

workspace_id · string · required

Identifier of the workspace whose messaging quota is nearing full utilization or reached.

Example:

"my-workspace"

event_type · enum<string> · required

Partner webhook event name.

Available options: workspace:quota_near_full:messaging, workspace:quota_full:messaging

Example:

"workspace:quota_full:messaging"

partner_id · string · required

Unique identifier of the partner that owns the workspace.

Example:

"partner_12345"

triggered_at · string<date-time> · required

Timestamp when the event was triggered.

Example:

"2024-01-01T12:00:00.000Z"

messaging_quota_total · integer · required

Total messaging quota allocated to the workspace for the current billing period.

Example:

100000

messaging_quota_used · integer · required

Number of messaging units consumed in the current billing period when the threshold was reached.

Example:

90000

current_period_start · string<date-time> · required

Start of the current billing period used to aggregate the utilization

Example:

"2024-01-01T00:00:00.000Z"

current_period_end · string<date-time> · required

End of the current billing period used to aggregate the utilization

Example:

"2024-01-31T23:59:59.000Z"

utilization_pct · integer

Messaging quota utilization percentage at the time of triggering, computed as an integer 0–100.

Example:

90

Response

200

Receiver accepted the event