# Account activity events

> The events that record what happens inside your ApiTraffic account, who did what and when, and how to read them from the app or the API.

Source: https://www.apitraffic.io/docs/webhooks/overview

> **Note:** This page and the [event reference](https://www.apitraffic.io/docs/webhooks/reference) are generated from
> `docs/events/account-activity.asyncapi.json`, which is itself built from the
> API's event registry. Spec version **1.0.0**, **96** customer-visible events.

Events describing what happens inside an ApiTraffic account: who did what, and when.

These are **account actions**, not captured API traffic. Creating a bucket, inviting a
teammate, revoking a token and changing a plan all appear here. The requests your
services handle do not.

## Delivery

Every event is written to a durable log before delivery is attempted, which is what makes
at-least-once delivery and replay possible. Expect redeliveries and deduplicate on `id`.

## Ordering

Not guaranteed. Order events by `occurredAt` rather than by arrival.

## Support sessions

When ApiTraffic support acts inside your account under a consent window you granted, the
event carries `actor.type: staff` and names them in `actor.impersonatedBy`. These are
delivered exactly like your own people’s actions, deliberately - access you cannot audit
is not access you agreed to.

## Where to read these events

Every event below is recorded in your account history as it happens. You can read it in two places.

### In the app

Open the account menu, choose **Account**, then the **History** tab. The **Account history** list shows each event with who did it and when, and lets you filter it. See [Activity log](https://www.apitraffic.io/docs/account/activity-log).

### Over the API

`GET /v1/accounts/{accountSid}/activity` returns the same events, newest first. Each record carries every [envelope](#envelope) field, plus the IP address and user agent of the person who acted (withheld when ApiTraffic support acted).

```bash
curl -s "https://api.apitraffic.io/v1/accounts/${APITRAFFIC_ACCOUNT_SID}/activity?category=security&limit=100" \
  -H "Authorization: Bearer ${APITRAFFIC_API_TOKEN}"
```

| Query parameter | Description |
| --- | --- |
| `category` | Only events in this category, such as `security` or `billing`. |
| `action` | Only this event type, such as `security.api_token_created`. |
| `severity` | `info`, `notice` or `critical`. |
| `actorUserSid` | Only events done by this person. |
| `targetSid` | Only events about this object. |
| `startTime`, `endTime` | ISO 8601 bounds on when the event occurred. |
| `limit` | 1 to 200. Defaults to 50. |
| `offset` | Skip this many events, for paging. The response includes `total`. |

`GET /v1/accounts/{accountSid}/activity/catalog` lists the event types that can appear in your account.

## Webhook delivery (coming soon)

> **Info:** Delivery of these events to an endpoint you register is coming soon. Until it ships,
> there is no webhook setting in the app and nothing is sent. To act on account activity
> today, poll the activity API above: it returns the same event objects.

The channel and envelope below are the delivery format events will be sent in. Build your consumer against them now, reading from the API today and switching to delivery when it ships:

- **Deduplicate on `id`.** The same event can arrive more than once.
- **Order by `occurredAt`,** not by the order you received events in.
- **Acknowledge quickly.** For a delivery, return a 2xx before doing slow work; any other status, or a timeout, is retried with backoff.
- **Read `actor.type` and `source` together** to tell a person changing something from a scheduled job changing the same thing.

## Channel

Delivery is coming soon. When it ships, each event is sent to your endpoint as follows.

`POST /webhooks/activity`

Events for one account, delivered to a URL you register.

Only customer-visible events appear here. ApiTraffic records additional internal
events for its own operations; those are never delivered and are not documented.

### Receive account activity

ApiTraffic sends these to your registered endpoint.

Respond 2xx to acknowledge. Any other status, or a timeout, is retried with backoff.
Acknowledge before doing slow work - a handler that blocks will be retried while it runs.

## Envelope

Every event carries the same envelope. The event-specific body is in `data`.

- **id (string, required)**:
  Unique id for this event. Stable across redeliveries, so it is what to deduplicate on. Example: `"act_3HrBcuMDtqwF8KlccVBKAzCpF7f"`.

- **type (string, required)**:
  The event type. One of the values enumerated by the channel.

- **category (string, required)**:
  Broad grouping, for routing and filtering. One of `"account"`, `"alerting"`, `"billing"`, `"bucket"`, `"data"`, `"integration"`, `"security"`, `"support"`, `"team"`.

- **severity (string, required)**:
  How much attention the event warrants. `critical` marks things worth alerting a human about. One of `"info"`, `"notice"`, `"critical"`.

- **accountSid (string, required)**:
  The account the event belongs to. Example: `"acc_2Zx9KpQwErTyUiOpAsDfGhJkL"`.

- **occurredAt (string, required)**:
  When the action happened. Not necessarily when it was delivered - a replayed or retried event keeps its original timestamp.

- **source (string | null)**:
  How the action reached us. `http` is a call to the API, usually somebody in the dashboard; `job` is scheduled or batch work running on our side; `webhook` is an upstream provider telling us something; `cli` is a command-line tool. Read alongside `actor.type`: together they distinguish a person making a change from a nightly job making the same one. One of `"http"`, `"job"`, `"webhook"`, `"cli"`.

- **actor (object, required)**:
  Who performed the action.

**actor**

- **type (string, required)**:
      Who acted. `user` is one of your people. `staff` is ApiTraffic support, acting under a consent window you granted. `api_token` is one of your own machine credentials - the action came from your systems, not from a person at a screen. `integration` is an upstream provider we act on behalf of, such as Stripe. `system` means no one was involved at all: scheduled work, a batch run, or an automatic consequence of something else. When it is `system`, `actor.sid` and `actor.label` are null and `source` tells you what kind of automation it was. One of `"user"`, `"staff"`, `"system"`, `"api_token"`, `"integration"`.

- **sid (string | null)**:
      The acting user, when there is one.

- **label (string | null)**:
      How the actor was identified at the time, usually an email address. Captured when the event was recorded, so it survives the user later being deleted.

- **impersonatedBy (string | null)**:
      Set only when ApiTraffic support performed this inside a support session. Null on everything else.

- **target (object | null)**:
  What was acted upon. Null for events that are about the account as a whole.

**target**

- **type (string)**:
      The kind of object, e.g. `bucket`.

- **sid (string | null)**:

- **label (string | null)**:
      The object’s name as it was at the time. Deliberately not updated if the object is later renamed.

- **summary (string | null)**:
  A rendered one-line description, as it read when the event happened. Safe to display directly.

## Event catalogue

96 events across 9 categories. Payload fields for each are in the [event reference](https://www.apitraffic.io/docs/webhooks/reference).

### Account

| Event | Severity | Summary |
| --- | --- | --- |
| [`account.client_ip_mode_changed`](https://www.apitraffic.io/docs/webhooks/reference#event-account-client-ip-mode-changed) | notice | An owner or admin changed how client IP addresses are kept on requests: in full, truncated to their network, or not at all. |
| [`account.close_cancelled`](https://www.apitraffic.io/docs/webhooks/reference#event-account-close-cancelled) | notice | A close scheduled for the end of the paid period was cancelled, and the subscription will renew. |
| [`account.close_scheduled`](https://www.apitraffic.io/docs/webhooks/reference#event-account-close-scheduled) | critical | The account will close, and its data be deleted, when the paid period ends. |
| [`account.closed`](https://www.apitraffic.io/docs/webhooks/reference#event-account-closed) | critical | The account was closed: access and capture stopped. Its captured data is deleted after the grace period (account.data_purge_completed). |
| [`account.created`](https://www.apitraffic.io/docs/webhooks/reference#event-account-created) | notice | The account was created. |
| [`account.data_purge_completed`](https://www.apitraffic.io/docs/webhooks/reference#event-account-data-purge-completed) | notice | A purge or close finished deleting the account's data. |
| [`account.data_purged`](https://www.apitraffic.io/docs/webhooks/reference#event-account-data-purged) | critical | A purge of the account's data was started: captured traffic, saved work, rules and settings, or automations, as chosen. account.data_purge_completed follows when it is done. Usage is not reduced. |
| [`account.environment_created`](https://www.apitraffic.io/docs/webhooks/reference#event-account-environment-created) | info | A new environment was added. |
| [`account.environment_deleted`](https://www.apitraffic.io/docs/webhooks/reference#event-account-environment-deleted) | notice | An environment was removed. |
| [`account.environment_updated`](https://www.apitraffic.io/docs/webhooks/reference#event-account-environment-updated) | info | An environment was changed. |
| [`account.name_changed`](https://www.apitraffic.io/docs/webhooks/reference#event-account-name-changed) | info | The account name was changed. |
| [`account.overage_toggled`](https://www.apitraffic.io/docs/webhooks/reference#event-account-overage-toggled) | notice | The account owner turned "Allow overage" on or off. Off, new requests and other metered usage are not recorded past the plan's allowance until the billing period resets, and no overage is billed. |
| [`account.query_text_toggled`](https://www.apitraffic.io/docs/webhooks/reference#event-account-query-text-toggled) | notice | An owner or admin turned on or off storing the text of database queries (and where they were called from) in performance data. |
| [`account.sample_data_toggled`](https://www.apitraffic.io/docs/webhooks/reference#event-account-sample-data-toggled) | info | An owner or admin showed or hid the read-only sample bucket for the team. |
| [`account.settings_updated`](https://www.apitraffic.io/docs/webhooks/reference#event-account-settings-updated) | info | A setting on the account was changed. |

### Alerting

| Event | Severity | Summary |
| --- | --- | --- |
| [`alerting.channel_changed`](https://www.apitraffic.io/docs/webhooks/reference#event-alerting-channel-changed) | notice | A notification channel was renamed or its destination or settings changed. |
| [`alerting.channel_created`](https://www.apitraffic.io/docs/webhooks/reference#event-alerting-channel-created) | notice | A notification channel (Slack, webhook, email, ...) was added. |
| [`alerting.channel_deleted`](https://www.apitraffic.io/docs/webhooks/reference#event-alerting-channel-deleted) | notice | A notification channel was removed. |
| [`alerting.channel_secret_rotated`](https://www.apitraffic.io/docs/webhooks/reference#event-alerting-channel-secret-rotated) | notice | A channel secret was replaced; the previous one stays valid for 24 hours. |
| [`alerting.delivery_log_viewed`](https://www.apitraffic.io/docs/webhooks/reference#event-alerting-delivery-log-viewed) | info | Someone opened the delivery attempts of a channel, which include response excerpts from the receiver. |
| [`alerting.delivery_redelivered`](https://www.apitraffic.io/docs/webhooks/reference#event-alerting-delivery-redelivered) | notice | A notification was sent again by hand from the delivery log. |
| [`alerting.incident_acknowledged`](https://www.apitraffic.io/docs/webhooks/reference#event-alerting-incident-acknowledged) | info | Someone acknowledged an incident; pending escalation steps are cancelled. |
| [`alerting.incident_owner_changed`](https://www.apitraffic.io/docs/webhooks/reference#event-alerting-incident-owner-changed) | info | An incident was assigned to someone else. |
| [`alerting.incident_reopened`](https://www.apitraffic.io/docs/webhooks/reference#event-alerting-incident-reopened) | info | An incident was reopened or returned to open by hand. |
| [`alerting.incident_resolved`](https://www.apitraffic.io/docs/webhooks/reference#event-alerting-incident-resolved) | info | An incident was resolved manually. |
| [`alerting.route_changed`](https://www.apitraffic.io/docs/webhooks/reference#event-alerting-route-changed) | notice | A routing policy was created, updated, reordered or removed. |
| [`alerting.silence_created`](https://www.apitraffic.io/docs/webhooks/reference#event-alerting-silence-created) | notice | A silence was created: matching alerts still fire but are not delivered. |
| [`alerting.silence_expired`](https://www.apitraffic.io/docs/webhooks/reference#event-alerting-silence-expired) | info | A silence was expired before its end time. |

### Billing

| Event | Severity | Summary |
| --- | --- | --- |
| [`billing.ingest_rate_limited`](https://www.apitraffic.io/docs/webhooks/reference#event-billing-ingest-rate-limited) | notice | Records were not recorded this billing period because the account sent more than its plan's records per second. Fires once per period. |
| [`billing.overage_resumed`](https://www.apitraffic.io/docs/webhooks/reference#event-billing-overage-resumed) | notice | Every overage invoice is settled; overage is billed again as the account allows. |
| [`billing.overage_suspended`](https://www.apitraffic.io/docs/webhooks/reference#event-billing-overage-suspended) | critical | Usage past an overage-billed allowance stops at the allowance until every overage invoice is paid. |
| [`billing.payment_failed`](https://www.apitraffic.io/docs/webhooks/reference#event-billing-payment-failed) | critical | A charge against the payment method failed. |
| [`billing.payment_method_updated`](https://www.apitraffic.io/docs/webhooks/reference#event-billing-payment-method-updated) | notice | The card or payment method on file was changed. |
| [`billing.plan_changed`](https://www.apitraffic.io/docs/webhooks/reference#event-billing-plan-changed) | notice | The subscription moved to a different plan. |
| [`billing.plan_over_limit`](https://www.apitraffic.io/docs/webhooks/reference#event-billing-plan-over-limit) | critical | A scheduled plan change took effect while the account held more of a resource than the new plan includes. Nothing was removed; new ones cannot be created until it is back within the limit. |
| [`billing.promotion_reward_ended`](https://www.apitraffic.io/docs/webhooks/reference#event-billing-promotion-reward-ended) | notice | A promotion reward expired or was withdrawn. |
| [`billing.promotion_reward_granted`](https://www.apitraffic.io/docs/webhooks/reference#event-billing-promotion-reward-granted) | notice | A referral or advocacy reward was applied to this account. |
| [`billing.subscription_cancelled`](https://www.apitraffic.io/docs/webhooks/reference#event-billing-subscription-cancelled) | critical | The subscription was cancelled. |
| [`billing.subscription_resumed`](https://www.apitraffic.io/docs/webhooks/reference#event-billing-subscription-resumed) | notice | A cancellation was reversed. |
| [`billing.trial_ended`](https://www.apitraffic.io/docs/webhooks/reference#event-billing-trial-ended) | notice | A trial period ended. |
| [`billing.trial_started`](https://www.apitraffic.io/docs/webhooks/reference#event-billing-trial-started) | info | A trial period began. |
| [`billing.usage_limit_reached`](https://www.apitraffic.io/docs/webhooks/reference#event-billing-usage-limit-reached) | critical | Usage hit the plan allowance. |

### Bucket

| Event | Severity | Summary |
| --- | --- | --- |
| [`bucket.created`](https://www.apitraffic.io/docs/webhooks/reference#event-bucket-created) | info | A new bucket was created. |
| [`bucket.deleted`](https://www.apitraffic.io/docs/webhooks/reference#event-bucket-deleted) | critical | A bucket and its configuration were deleted. |
| [`bucket.updated`](https://www.apitraffic.io/docs/webhooks/reference#event-bucket-updated) | info | A bucket setting was changed. |

### Data

| Event | Severity | Summary |
| --- | --- | --- |
| [`data.catalog_changed`](https://www.apitraffic.io/docs/webhooks/reference#event-data-catalog-changed) | info | Customer catalogue entries (labels and attributes of tag values) were added, replaced or removed. |
| [`data.dashboard_created`](https://www.apitraffic.io/docs/webhooks/reference#event-data-dashboard-created) | info | A report dashboard was created. |
| [`data.dashboard_deleted`](https://www.apitraffic.io/docs/webhooks/reference#event-data-dashboard-deleted) | info | A report dashboard was deleted (its reports are kept). |
| [`data.dashboard_updated`](https://www.apitraffic.io/docs/webhooks/reference#event-data-dashboard-updated) | info | A dashboard was renamed, rearranged, refiltered or shared differently. |
| [`data.dimension_classified`](https://www.apitraffic.io/docs/webhooks/reference#event-data-dimension-classified) | notice | A tag key's classification changed (which decides masking and where its values may go), or it became or stopped being the customer key. |
| [`data.dimension_demoted`](https://www.apitraffic.io/docs/webhooks/reference#event-data-dimension-demoted) | notice | A tag key is no longer aggregated; reports on it read raw rows. |
| [`data.dimension_promoted`](https://www.apitraffic.io/docs/webhooks/reference#event-data-dimension-promoted) | notice | A tag key was promoted to fast, pre-aggregated reports. |
| [`data.dimension_updated`](https://www.apitraffic.io/docs/webhooks/reference#event-data-dimension-updated) | info | A tag key was renamed, described, hidden or shown again. |
| [`data.embed_disabled`](https://www.apitraffic.io/docs/webhooks/reference#event-data-embed-disabled) | notice | A report or dashboard stopped allowing embedding (turned off, or made private); its embeds stop showing it. |
| [`data.embed_enabled`](https://www.apitraffic.io/docs/webhooks/reference#event-data-embed-enabled) | critical | A report or dashboard can now be shown by embed tokens the account signs. |
| [`data.exclusion_changed`](https://www.apitraffic.io/docs/webhooks/reference#event-data-exclusion-changed) | notice | A rule governing which traffic is captured was changed. |
| [`data.redaction_changed`](https://www.apitraffic.io/docs/webhooks/reference#event-data-redaction-changed) | critical | A rule governing what data is redacted before storage was changed. |
| [`data.report_created`](https://www.apitraffic.io/docs/webhooks/reference#event-data-report-created) | info | A custom report was saved, from scratch or from a template. |
| [`data.report_deleted`](https://www.apitraffic.io/docs/webhooks/reference#event-data-report-deleted) | info | A saved report was deleted, with its revisions; dashboard tiles showing it were removed. |
| [`data.report_updated`](https://www.apitraffic.io/docs/webhooks/reference#event-data-report-updated) | info | A saved report was renamed, redefined, redrawn, moved, pinned or shared differently. |
| [`data.retention_changed`](https://www.apitraffic.io/docs/webhooks/reference#event-data-retention-changed) | notice | How long captured traffic is kept was changed. |
| [`data.share_created`](https://www.apitraffic.io/docs/webhooks/reference#event-data-share-created) | critical | Data was made reachable through a share link. |
| [`data.share_revoked`](https://www.apitraffic.io/docs/webhooks/reference#event-data-share-revoked) | notice | A share link was disabled. |

### Integration

| Event | Severity | Summary |
| --- | --- | --- |
| [`integration.git_connected`](https://www.apitraffic.io/docs/webhooks/reference#event-integration-git-connected) | notice | A git provider was connected to the account. |
| [`integration.git_disconnected`](https://www.apitraffic.io/docs/webhooks/reference#event-integration-git-disconnected) | notice | A git provider connection was removed. |
| [`integration.webhook_changed`](https://www.apitraffic.io/docs/webhooks/reference#event-integration-webhook-changed) | notice | An outbound webhook was created, updated or removed. |
| [`integration.workflow_changed`](https://www.apitraffic.io/docs/webhooks/reference#event-integration-workflow-changed) | info | A workflow was created, updated or removed. |

### Security

| Event | Severity | Summary |
| --- | --- | --- |
| [`security.api_token_access_changed`](https://www.apitraffic.io/docs/webhooks/reference#event-security-api-token-access-changed) | critical | An API token's role or access scopes were changed. |
| [`security.api_token_created`](https://www.apitraffic.io/docs/webhooks/reference#event-security-api-token-created) | critical | A new API token was minted. |
| [`security.api_token_revoked`](https://www.apitraffic.io/docs/webhooks/reference#event-security-api-token-revoked) | notice | An API token was revoked. |
| [`security.mcp_token_created`](https://www.apitraffic.io/docs/webhooks/reference#event-security-mcp-token-created) | critical | A new MCP token was minted. |
| [`security.mcp_token_revoked`](https://www.apitraffic.io/docs/webhooks/reference#event-security-mcp-token-revoked) | notice | An MCP token was revoked. |
| [`security.mfa_disabled`](https://www.apitraffic.io/docs/webhooks/reference#event-security-mfa-disabled) | critical | A member turned MFA off. |
| [`security.mfa_enabled`](https://www.apitraffic.io/docs/webhooks/reference#event-security-mfa-enabled) | notice | A member enrolled in MFA. |
| [`security.mfa_required_changed`](https://www.apitraffic.io/docs/webhooks/reference#event-security-mfa-required-changed) | critical | The account changed whether MFA is mandatory for everyone. |
| [`security.mfa_reset`](https://www.apitraffic.io/docs/webhooks/reference#event-security-mfa-reset) | critical | A member's MFA enrolment was reset, usually by support. |
| [`security.oauth_app_authorized`](https://www.apitraffic.io/docs/webhooks/reference#event-security-oauth-app-authorized) | critical | A person authorized an application to access the account. |
| [`security.oauth_app_revoked`](https://www.apitraffic.io/docs/webhooks/reference#event-security-oauth-app-revoked) | notice | An application's access to the account was revoked. |
| [`security.passkey_added`](https://www.apitraffic.io/docs/webhooks/reference#event-security-passkey-added) | critical | A new passkey was registered as a sign-in method. |
| [`security.passkey_removed`](https://www.apitraffic.io/docs/webhooks/reference#event-security-passkey-removed) | notice | A passkey was removed as a sign-in method. |
| [`security.password_changed`](https://www.apitraffic.io/docs/webhooks/reference#event-security-password-changed) | notice | A member changed their password. |
| [`security.signed_in`](https://www.apitraffic.io/docs/webhooks/reference#event-security-signed-in) | info | Somebody signed in to the account. |
| [`security.signed_out`](https://www.apitraffic.io/docs/webhooks/reference#event-security-signed-out) | info | Somebody deliberately ended their session. |
| [`security.sms_added`](https://www.apitraffic.io/docs/webhooks/reference#event-security-sms-added) | critical | A phone number was verified and registered as a sign-in method. |
| [`security.sms_consent_granted`](https://www.apitraffic.io/docs/webhooks/reference#event-security-sms-consent-granted) | notice | Consent to receive text-message verification codes was given, before any message was sent. |
| [`security.sms_removed`](https://www.apitraffic.io/docs/webhooks/reference#event-security-sms-removed) | notice | A phone number was removed as a sign-in method. |

### Support

| Event | Severity | Summary |
| --- | --- | --- |
| [`support.access_granted`](https://www.apitraffic.io/docs/webhooks/reference#event-support-access-granted) | critical | The account opened a staff-access consent window. |
| [`support.access_revoked`](https://www.apitraffic.io/docs/webhooks/reference#event-support-access-revoked) | notice | The account closed its staff-access consent window. |
| [`support.session_started`](https://www.apitraffic.io/docs/webhooks/reference#event-support-session-started) | critical | A member of staff began an impersonated session. |

### Team

| Event | Severity | Summary |
| --- | --- | --- |
| [`team.invitation_accepted`](https://www.apitraffic.io/docs/webhooks/reference#event-team-invitation-accepted) | notice | An invitation was accepted and the person joined. |
| [`team.invitation_revoked`](https://www.apitraffic.io/docs/webhooks/reference#event-team-invitation-revoked) | notice | A pending invitation was withdrawn. |
| [`team.member_added`](https://www.apitraffic.io/docs/webhooks/reference#event-team-member-added) | notice | Somebody was granted access to the account. |
| [`team.member_invited`](https://www.apitraffic.io/docs/webhooks/reference#event-team-member-invited) | notice | Somebody was invited to join the account. |
| [`team.member_removed`](https://www.apitraffic.io/docs/webhooks/reference#event-team-member-removed) | notice | Somebody lost access to the account. |
| [`team.primary_changed`](https://www.apitraffic.io/docs/webhooks/reference#event-team-primary-changed) | critical | Ownership of the account moved to a different person. |
| [`team.role_changed`](https://www.apitraffic.io/docs/webhooks/reference#event-team-role-changed) | notice | A member's role was changed. |