> ## Documentation Index
> Fetch the complete documentation index at: https://timelines.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Partner API Webhooks Overview

> Receive real-time notifications for workspace, account, and quota events across your managed workspaces

# Partner API Webhooks

PartnerAPI Webhooks notify your platform in real-time when important events occur across the workspaces you manage. Monitor quota usage, track WhatsApp account connections, and stay informed about API token changes — all without polling.

These webhooks are separate from the PublicAPI Webhooks. While PublicAPI Webhooks cover message-level and chat-level events within a single workspace, PartnerAPI Webhooks focus on workspace-level operational events relevant to platform administrators and resellers.

## Available events

### Workspace quota events

Get alerted when your managed workspaces approach or hit their usage limits. These events enable proactive billing management and prevent service interruptions.

| Event | Trigger | Description |
| - | - | - |
| Seats fully utilized | All seats in use | Every purchased seat in the workspace is occupied — no more users can be added |
| Messaging quota at 90% | Nearing message limit | The workspace has used 90% or more of its messaging quota for the current billing period |
| Messaging quota at 100% | Message limit reached | The workspace has exhausted its messaging quota — new messages will be blocked |
| Transactions quota exhausted | Transaction limit reached | All available transactions for the workspace have been consumed |
| API calls quota at 100% | API call limit reached | The workspace has used 100% of its Public API call quota for the current billing period |

### WhatsApp account events

Track when WhatsApp numbers are connected or disconnected across your managed workspaces.

| Event | Trigger | Description |
| - | - | - |
| Account connected | WhatsApp linked | A user successfully connected a WhatsApp account by scanning a QR code |
| Account disconnected | WhatsApp unlinked | A WhatsApp account was disconnected (manually or automatically) |

### API token events

Monitor security-sensitive changes to Public API tokens.

| Event | Trigger | Description |
| - | - | - |
| Token rotated | Public API token changed | A workspace's Public API token was rotated via the Partner API |

## Use case examples

> [accordion] Proactive quota management
>
> Prevent service disruptions by acting on quota warnings before limits are reached.
>
> 1. Subscribe to the 90% messaging quota event
> 2. When triggered, notify your customer that they are approaching their limit
> 3. Offer an upsell or auto-upgrade their plan
> 4. If the 100% event fires, display a warning in your UI and queue messages for later

> [accordion] Automated billing & usage tracking
>
> Keep your billing system in sync with actual resource consumption.
>
> 1. Subscribe to all quota events (seats, messaging, transactions, API calls)
> 2. Log each event with the workspace ID and timestamp
> 3. Trigger billing adjustments, overage charges, or plan upgrades automatically
> 4. Generate usage reports for your customers

> [accordion] Onboarding status tracking
>
> Know instantly when a customer's WhatsApp account is ready.
>
> 1. After generating a QR code via the Partner API, subscribe to the `account connected` event
> 2. When the event fires, update your onboarding flow to mark WhatsApp as connected
> 3. Trigger welcome messages or next-step guides for the customer
> 4. Monitor for disconnections and prompt users to reconnect

> [accordion] Security monitoring
>
> Track API token changes and account access across all workspaces.
>
> 1. Subscribe to the `token rotated` event to audit all token changes
> 2. Log which workspaces had tokens rotated and when
> 3. Subscribe to account disconnection events to detect unexpected access changes
> 4. Alert your security team if a workspace loses its WhatsApp connection unexpectedly

## Payload example

When a workspace's messaging quota reaches 90%, your endpoint receives:

```json theme={null}
{
  "event_type": "workspace:messaging_quota:90",
  "data": {
    "workspace_id": 12345,
    "quota_limit": 10000,
    "quota_used": 9150,
    "billing_period_end": "2024-02-01T00:00:00Z"
  }
}
```

## Best practices

* **Act on 90% warnings** — don't wait for the 100% event. Proactively notify customers or auto-scale their plans.
* **Log all events** — maintain an audit trail of all webhook events for billing reconciliation and support troubleshooting.
* **Monitor account connectivity** — WhatsApp disconnections can disrupt your customer's business. React to disconnection events quickly.
* **Secure token rotation** — when you receive a `token rotated` event, update any cached tokens in your system immediately.

## Next steps

> [card] [Partner API](https://timelines.ai/docs/partner-api-reference/overview.md)
>
> Manage workspaces, users, and accounts

> [card] [PublicAPI Webhooks](https://timelines.ai/docs/webhook-reference/overview.md)
>
> Message and chat-level event notifications


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.