Webhooks
List webhook event catalog
Returns the supported webhook event types with, for each one, its description, exact trigger condition, payload schema and an example payload, plus the delivery envelope and signature scheme. Read it before subscribing: several names are counter-intuitive — account.published fires when you publish the order, not when the account is delivered (that is account.in_review), and warming.session_started is not emitted for warming whose terms were set at bundle creation. This endpoint is public so teams can inspect webhook contracts before creating an API key.
get/webhooks/events
Request
- Base URL: https://app.tokportal.com/api/ext
- URL: https://app.tokportal.com/api/ext/webhooks/events
- Auth: none required
Response
Supported webhook events and delivery contract.
Example response
{
"data": {
"events": [
{
"type": "webhook.test",
"category": "webhook",
"availability": "emitted",
"description": "A signed test event sent on demand to validate an endpoint.",
"when": "Sent when you call POST /webhooks/{id}/test.",
"payload_schema": {
"type": "object",
"required": [
"webhook_endpoint_id",
"message"
],
"properties": {
"webhook_endpoint_id": {
"type": "string",
"format": "uuid"
},
"message": {
"type": "string"
}
}
},
"example_payload": {
"webhook_endpoint_id": "33333333-4444-4555-8666-777777777777",
"message": "TokPortal webhook test event"
}
},
{
"type": "bundle.created",
"category": "bundle",
"availability": "emitted",
"description": "A bundle was created through the public API.",
"when": "Emitted after a successful bundle creation.",
"payload_schema": {
"type": "object",
"required": [
"bundle_id"
],
"properties": {
"bundle_id": {
"type": "string",
"format": "uuid"
},
"external_ref": {
"type": [
"string",
"null"
]
},
"status": {
"type": "string"
},
"platform": {
"type": "string"
},
"bundle_type": {
"type": "string"
}
}
},
"example_payload": {
"bundle_id": "9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c",
"external_ref": "partner-order-123",
"status": "pending_setup",
"platform": "tiktok",
"bundle_type": "account_and_videos"
}
},
{
"type": "bundle.published",
"category": "bundle",
"availability": "emitted",
"description": "A bundle was published.",
"when": "Emitted after a bundle publish request succeeds.",
"payload_schema": {
"type": "object",
"required": [
"bundle_id"
],
"properties": {
"bundle_id": {
"type": "string",
"format": "uuid"
},
"external_ref": {
"type": [
"string",
"null"
]
},
"status": {
"type": "string"
},
"platform": {
"type": "string"
},
"bundle_type": {
"type": "string"
}
}
},
"example_payload": {
"bundle_id": "9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c",
"external_ref": "partner-order-123",
"status": "published",
"platform": "tiktok",
"bundle_type": "account_and_videos"
}
},
{
"type": "bundle.cancelled",
"category": "bundle",
"availability": "emitted",
"description": "A bundle was cancelled. No further videos will be posted on it.",
"when": "Emitted when a bundle is cancelled: the bundle's account was banned (validated ban report with account_banned=true, and an account.banned event fires alongside), a ban-check was accepted with the cancel and refund resolution, or staff cancelled the bundle manually. Publishing to a cancelled bundle returns 409 BUNDLE_INVALID_STATUS.",
"payload_schema": {
"type": "object",
"required": [
"bundle_id",
"reason",
"cancelled_at"
],
"properties": {
"bundle_id": {
"type": "string",
"format": "uuid"
},
"external_ref": {
"type": [
"string",
"null"
]
},
"platform": {
"type": "string"
},
"reason": {
"type": "string"
},
"cancelled_at": {
"type": "string",
"format": "date-time"
},
"account_banned": {
"type": "boolean",
"description": "True when the cancellation was caused by the bundle's account being banned. An account.banned event fires alongside."
},
"saved_account_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"username": {
"type": [
"string",
"null"
]
}
}
},
"example_payload": {
"bundle_id": "9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c",
"external_ref": "partner-order-123",
"platform": "tiktok",
"reason": "Account banned: Community guidelines violation",
"cancelled_at": "2026-07-06T19:13:43Z",
"account_banned": true,
"saved_account_id": "7c9e0f1a-2b3c-4d5e-8f6a-1b2c3d4e5f60",
"username": "launchprofile"
}
},
{
"type": "bundle.archived",
"category": "bundle",
"availability": "emitted",
"description": "An inactive bundle was archived from the manager workspace without changing TokPortal Coverage.",
"when": "Emitted after 60 days with no newly scheduled or posted video and no executable video task. New work can reopen the bundle.",
"payload_schema": {
"type": "object",
"required": [
"bundle_id"
],
"properties": {
"bundle_id": {
"type": "string",
"format": "uuid"
},
"external_ref": {
"type": [
"string",
"null"
]
},
"status": {
"type": "string"
},
"platform": {
"type": "string"
},
"bundle_type": {
"type": "string"
}
}
},
"example_payload": {
"bundle_id": "11111111-2222-4333-8444-555555555555",
"external_ref": "campaign-august-01",
"status": "completed",
"archived_at": "2026-10-09T11:00:00Z",
"reason": "no_scheduled_or_posted_video_for_60_days",
"account_coverage_changed": false
}
},
{
"type": "account.configured",
"category": "account",
"availability": "emitted",
"description": "An account listing was configured.",
"when": "Emitted when PUT /bundles/{id}/account moves an account listing to configured.",
"payload_schema": {
"type": "object",
"required": [
"account_id",
"bundle_id",
"status"
],
"properties": {
"account_id": {
"type": "string",
"format": "uuid"
},
"saved_account_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"bundle_id": {
"type": "string",
"format": "uuid"
},
"username": {
"type": [
"string",
"null"
]
},
"platform": {
"type": "string"
},
"status": {
"type": "string"
},
"previous_status": {
"type": [
"string",
"null"
]
}
}
},
"example_payload": {
"account_id": "0d1e2f3a-4b5c-6789-8abc-def012345678",
"saved_account_id": null,
"bundle_id": "9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c",
"username": "launchprofile",
"platform": "tiktok",
"status": "configured",
"previous_status": "pending"
}
},
{
"type": "account.in_review",
"category": "account",
"availability": "emitted",
"description": "An account listing entered customer review.",
"when": "Emitted whenever an account listing enters in_review, whatever moved it there — a manager submitting or resubmitting from the web or mobile app, a Bundle Social handoff, or an operator action. Delivered by a log drain rather than inline with the write, so expect up to a few minutes of lag.",
"payload_schema": {
"type": "object",
"required": [
"account_id",
"bundle_id",
"status"
],
"properties": {
"account_id": {
"type": "string",
"format": "uuid"
},
"saved_account_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"bundle_id": {
"type": "string",
"format": "uuid"
},
"username": {
"type": [
"string",
"null"
]
},
"platform": {
"type": "string"
},
"status": {
"type": "string"
},
"previous_status": {
"type": [
"string",
"null"
]
}
}
},
"example_payload": {
"account_id": "0d1e2f3a-4b5c-6789-8abc-def012345678",
"saved_account_id": "7c9e0f1a-2b3c-4d5e-8f6a-1b2c3d4e5f60",
"bundle_id": "9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c",
"username": "launchprofile",
"platform": "tiktok",
"status": "in_review",
"previous_status": "accepted"
}
},
{
"type": "account.published",
"category": "account",
"availability": "emitted",
"description": "An account listing was published to an active bundle.",
"when": "Emitted when POST /bundles/{id}/publish moves a configured account listing to published.",
"payload_schema": {
"type": "object",
"required": [
"account_id",
"bundle_id",
"status"
],
"properties": {
"account_id": {
"type": "string",
"format": "uuid"
},
"saved_account_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"bundle_id": {
"type": "string",
"format": "uuid"
},
"username": {
"type": [
"string",
"null"
]
},
"platform": {
"type": "string"
},
"status": {
"type": "string"
},
"previous_status": {
"type": [
"string",
"null"
]
}
}
},
"example_payload": {
"account_id": "0d1e2f3a-4b5c-6789-8abc-def012345678",
"saved_account_id": null,
"bundle_id": "9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c",
"username": "launchprofile",
"platform": "tiktok",
"status": "published",
"previous_status": "configured"
}
},
{
"type": "account.pending_corrections",
"category": "account",
"availability": "emitted",
"description": "Corrections were requested for an account listing.",
"when": "Emitted after POST /bundles/{id}/account/corrections moves an account listing from in_review to pending_corrections.",
"payload_schema": {
"type": "object",
"required": [
"account_id",
"bundle_id",
"status"
],
"properties": {
"account_id": {
"type": "string",
"format": "uuid"
},
"saved_account_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"bundle_id": {
"type": "string",
"format": "uuid"
},
"username": {
"type": [
"string",
"null"
]
},
"platform": {
"type": "string"
},
"status": {
"type": "string"
},
"previous_status": {
"type": [
"string",
"null"
]
}
}
},
"example_payload": {
"account_id": "0d1e2f3a-4b5c-6789-8abc-def012345678",
"saved_account_id": "7c9e0f1a-2b3c-4d5e-8f6a-1b2c3d4e5f60",
"bundle_id": "9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c",
"username": "launchprofile",
"platform": "tiktok",
"status": "pending_corrections",
"previous_status": "in_review"
}
},
{
"type": "account.finalized",
"category": "account",
"availability": "emitted",
"description": "An account listing was approved and finalized.",
"when": "Emitted after POST /bundles/{id}/account/finalize succeeds.",
"payload_schema": {
"type": "object",
"required": [
"account_id",
"bundle_id",
"status"
],
"properties": {
"account_id": {
"type": "string",
"format": "uuid"
},
"saved_account_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"bundle_id": {
"type": "string",
"format": "uuid"
},
"username": {
"type": [
"string",
"null"
]
},
"platform": {
"type": "string"
},
"status": {
"type": "string"
},
"previous_status": {
"type": [
"string",
"null"
]
}
}
},
"example_payload": {
"account_id": "0d1e2f3a-4b5c-6789-8abc-def012345678",
"saved_account_id": "7c9e0f1a-2b3c-4d5e-8f6a-1b2c3d4e5f60",
"bundle_id": "9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c",
"username": "launchprofile",
"platform": "tiktok",
"status": "finalized",
"previous_status": "in_review"
}
},
{
"type": "account.remade",
"category": "account",
"availability": "emitted",
"description": "An account was remade after the previous one was banned or lost.",
"when": "Emitted when a bundle/account is remade. The previous saved account is removed and the bundle is rebuilt in place under the SAME bundle_id (use it, or your external_ref, as the stable anchor). The rebuilt account is created later by the manager and surfaces through subsequent account.* events on the same bundle_id.",
"payload_schema": {
"type": "object",
"required": [
"bundle_id",
"remade_count"
],
"properties": {
"bundle_id": {
"type": "string",
"format": "uuid"
},
"external_ref": {
"type": [
"string",
"null"
]
},
"platform": {
"type": "string"
},
"old_username": {
"type": [
"string",
"null"
]
},
"new_username": {
"type": [
"string",
"null"
]
},
"old_account_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"reason": {
"type": [
"string",
"null"
]
},
"mode": {
"type": "string"
},
"remade_count": {
"type": "integer",
"minimum": 1
},
"remade_at": {
"type": [
"string",
"null"
],
"format": "date-time"
}
}
},
"example_payload": {
"bundle_id": "9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c",
"external_ref": "partner-order-123",
"platform": "tiktok",
"old_username": "launchprofile",
"new_username": "launchprofile_",
"old_account_id": "0d1e2f3a-4b5c-6789-8abc-def012345678",
"reason": "account banned/not found",
"mode": "republish",
"remade_count": 1,
"remade_at": "2026-06-09T00:36:24Z"
}
},
{
"type": "account.banned",
"category": "account",
"availability": "emitted",
"description": "An account managed for one of your bundles was banned by the platform.",
"when": "Emitted when the manager reports a ban and no appeal was available, or when the platform refused the ban appeal. The saved account is marked banned (banned_at/banned_reason) but stays visible. Staff reviews every ban report.",
"payload_schema": {
"type": "object",
"required": [
"bundle_id",
"appeal_status"
],
"properties": {
"bundle_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"saved_account_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"username": {
"type": [
"string",
"null"
]
},
"platform": {
"type": "string"
},
"reason": {
"type": [
"string",
"null"
]
},
"appeal_status": {
"type": "string",
"enum": [
"appeal_refused",
"no_appeal_banned"
]
},
"banned_at": {
"type": "string",
"format": "date-time"
}
}
},
"example_payload": {
"bundle_id": "9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c",
"saved_account_id": "7c9e0f1a-2b3c-4d5e-8f6a-1b2c3d4e5f60",
"username": "launchprofile",
"platform": "tiktok",
"reason": "Community guidelines violation notice shown in-app",
"appeal_status": "appeal_refused",
"banned_at": "2026-07-03T10:15:00Z"
}
},
{
"type": "account.ban_appeal.submitted",
"category": "account",
"availability": "emitted",
"description": "The manager filed a platform ban appeal for an account managed for one of your bundles.",
"when": "Emitted when the manager reports a ban AND files a platform appeal. The account is unavailable while the appeal is pending, but it is NOT yet marked banned (no account.banned event fires, bundles stay open). A later account.ban_appeal.resolved event carries the platform's decision.",
"payload_schema": {
"type": "object",
"required": [
"appeal_id",
"appeal_status",
"submitted_at"
],
"properties": {
"appeal_id": {
"type": "string",
"format": "uuid"
},
"bundle_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"saved_account_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"username": {
"type": [
"string",
"null"
]
},
"platform": {
"type": "string"
},
"appeal_status": {
"type": "string",
"enum": [
"appeal_pending"
]
},
"submitted_at": {
"type": "string",
"format": "date-time"
}
}
},
"example_payload": {
"appeal_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d",
"bundle_id": "9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c",
"saved_account_id": "7c9e0f1a-2b3c-4d5e-8f6a-1b2c3d4e5f60",
"username": "launchprofile",
"platform": "tiktok",
"appeal_status": "appeal_pending",
"submitted_at": "2026-07-01T08:30:00Z"
}
},
{
"type": "account.ban_appeal.resolved",
"category": "account",
"availability": "emitted",
"description": "A platform ban appeal filed by the manager reached a final decision.",
"when": "Emitted when the manager reports the platform's answer to a ban appeal: resolution 'appeal_accepted' (account survived, nothing else changes) or 'appeal_refused' (the account is banned, and an account.banned event fires alongside).",
"payload_schema": {
"type": "object",
"required": [
"appeal_id",
"resolution"
],
"properties": {
"appeal_id": {
"type": "string",
"format": "uuid"
},
"bundle_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"saved_account_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"username": {
"type": [
"string",
"null"
]
},
"platform": {
"type": "string"
},
"resolution": {
"type": "string",
"enum": [
"appeal_accepted",
"appeal_refused"
]
},
"reason": {
"type": [
"string",
"null"
]
},
"decided_at": {
"type": "string",
"format": "date-time"
}
}
},
"example_payload": {
"appeal_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d",
"bundle_id": "9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c",
"saved_account_id": "7c9e0f1a-2b3c-4d5e-8f6a-1b2c3d4e5f60",
"username": "launchprofile",
"platform": "tiktok",
"resolution": "appeal_refused",
"reason": "Community guidelines violation notice shown in-app",
"decided_at": "2026-07-03T10:15:00Z"
}
},
{
"type": "account.ban_resolution.decided",
"category": "account",
"availability": "emitted",
"description": "Staff decided the commercial outcome of a confirmed ban: refund, remake, or no_remake.",
"when": "Emitted when staff resolves a confirmed ban report (status appeal_refused or no_appeal_banned) from the Ban Appeals queue: 'refund' restores credits (refund_credits carries the amount and a credits.restored event can fire alongside), 'remake' resets and relists the mission under the same bundle_id (an account.remade event fires alongside), and 'no_remake' closes the case without compensation (reason_code 'tos_ban' means the account was banned for a direct Terms of Service violation).",
"payload_schema": {
"type": "object",
"required": [
"appeal_id",
"resolution",
"resolved_at"
],
"properties": {
"appeal_id": {
"type": "string",
"format": "uuid"
},
"bundle_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"saved_account_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"username": {
"type": [
"string",
"null"
]
},
"platform": {
"type": "string"
},
"resolution": {
"type": "string",
"enum": [
"refund",
"remake",
"no_remake"
],
"description": "Commercial outcome decided by staff: refund (credits restored), remake (the mission is reset and relisted — an account.remade event fires alongside), or no_remake (no compensation; see reason_code)."
},
"reason_code": {
"type": [
"string",
"null"
],
"description": "Machine-readable resolution reason, e.g. eligible_refund, eligible_credit_restoration, replacement_approved, tos_ban, tos_violation, content_related, custom."
},
"refund_credits": {
"type": "integer",
"minimum": 0
},
"resolved_at": {
"type": "string",
"format": "date-time"
}
}
},
"example_payload": {
"appeal_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d",
"bundle_id": "9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c",
"saved_account_id": "7c9e0f1a-2b3c-4d5e-8f6a-1b2c3d4e5f60",
"username": "launchprofile",
"platform": "tiktok",
"resolution": "refund",
"reason_code": "eligible_refund",
"refund_credits": 42,
"resolved_at": "2026-07-04T16:45:00Z"
}
},
{
"type": "video.configured",
"category": "video",
"availability": "emitted",
"description": "A video listing was configured or unscheduled back to configured.",
"when": "Emitted when a video configuration, CSV import, batch configuration, or unschedule action moves a video listing to configured.",
"payload_schema": {
"type": "object",
"required": [
"video_id",
"bundle_id",
"position",
"status"
],
"properties": {
"video_id": {
"type": "string",
"format": "uuid"
},
"bundle_id": {
"type": "string",
"format": "uuid"
},
"position": {
"type": "integer",
"minimum": 1
},
"status": {
"type": "string"
},
"previous_status": {
"type": [
"string",
"null"
]
},
"platform_url": {
"type": [
"string",
"null"
],
"format": "uri"
}
}
},
"example_payload": {
"video_id": "11111111-2222-4333-8444-555555555555",
"bundle_id": "9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c",
"position": 1,
"status": "configured",
"previous_status": "pending",
"platform_url": null
}
},
{
"type": "video.in_review",
"category": "video",
"availability": "emitted",
"description": "A video listing entered customer review.",
"when": "Emitted when a manager submits a posted video URL and the video listing moves to in_review.",
"payload_schema": {
"type": "object",
"required": [
"video_id",
"bundle_id",
"position",
"status"
],
"properties": {
"video_id": {
"type": "string",
"format": "uuid"
},
"bundle_id": {
"type": "string",
"format": "uuid"
},
"position": {
"type": "integer",
"minimum": 1
},
"status": {
"type": "string"
},
"previous_status": {
"type": [
"string",
"null"
]
},
"platform_url": {
"type": [
"string",
"null"
],
"format": "uri"
}
}
},
"example_payload": {
"video_id": "11111111-2222-4333-8444-555555555555",
"bundle_id": "9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c",
"position": 1,
"status": "in_review",
"previous_status": "configured",
"platform_url": null
}
},
{
"type": "video.published",
"category": "video",
"availability": "emitted",
"description": "A video was published to its destination platform.",
"when": "Emitted after POST /bundles/{id}/videos/{position}/publish succeeds.",
"payload_schema": {
"type": "object",
"required": [
"video_id",
"bundle_id",
"position",
"status"
],
"properties": {
"video_id": {
"type": "string",
"format": "uuid"
},
"bundle_id": {
"type": "string",
"format": "uuid"
},
"position": {
"type": "integer",
"minimum": 1
},
"status": {
"type": "string"
},
"previous_status": {
"type": [
"string",
"null"
]
},
"platform_url": {
"type": [
"string",
"null"
],
"format": "uri"
}
}
},
"example_payload": {
"video_id": "11111111-2222-4333-8444-555555555555",
"bundle_id": "9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c",
"position": 1,
"status": "published",
"previous_status": "in_review",
"platform_url": "https://www.tiktok.com/@launchprofile/video/123"
}
},
{
"type": "video.pending_corrections",
"category": "video",
"availability": "emitted",
"description": "Corrections were requested for a video listing.",
"when": "Emitted after POST /bundles/{id}/videos/{position}/corrections moves a video listing from in_review to pending_corrections.",
"payload_schema": {
"type": "object",
"required": [
"video_id",
"bundle_id",
"position",
"status"
],
"properties": {
"video_id": {
"type": "string",
"format": "uuid"
},
"bundle_id": {
"type": "string",
"format": "uuid"
},
"position": {
"type": "integer",
"minimum": 1
},
"status": {
"type": "string"
},
"previous_status": {
"type": [
"string",
"null"
]
},
"platform_url": {
"type": [
"string",
"null"
],
"format": "uri"
}
}
},
"example_payload": {
"video_id": "11111111-2222-4333-8444-555555555555",
"bundle_id": "9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c",
"position": 1,
"status": "pending_corrections",
"previous_status": "in_review",
"platform_url": "https://www.tiktok.com/@launchprofile/video/123"
}
},
{
"type": "video.finalized",
"category": "video",
"availability": "emitted",
"description": "A video passed final review.",
"when": "Emitted after POST /bundles/{id}/videos/{position}/finalize succeeds.",
"payload_schema": {
"type": "object",
"required": [
"video_id",
"bundle_id",
"position",
"status"
],
"properties": {
"video_id": {
"type": "string",
"format": "uuid"
},
"bundle_id": {
"type": "string",
"format": "uuid"
},
"position": {
"type": "integer",
"minimum": 1
},
"status": {
"type": "string"
},
"previous_status": {
"type": [
"string",
"null"
]
},
"platform_url": {
"type": [
"string",
"null"
],
"format": "uri"
}
}
},
"example_payload": {
"video_id": "11111111-2222-4333-8444-555555555555",
"bundle_id": "9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c",
"position": 1,
"status": "finalized",
"previous_status": "in_review",
"platform_url": "https://www.tiktok.com/@launchprofile/video/123"
}
},
{
"type": "warming.session_started",
"category": "warming",
"availability": "emitted",
"description": "An advanced warming session started on one of your accounts.",
"when": "Emitted when POST /accounts/{id}/rewarm creates a session (it starts immediately), and when configuring the niche targets of a count-only purchase (PUT /bundles/{id}/account with advanced_warming_terms) starts the session because the account/order is already active. Bundle-sourced sessions whose targets were set at creation start via an internal transition when the manager begins working on the account and do NOT emit this event. Track them through GET /warming-sessions/{id} or GET /accounts/{id}/warming-sessions instead.",
"payload_schema": {
"type": "object",
"required": [
"session_id",
"terms_total"
],
"properties": {
"session_id": {
"type": "string",
"format": "uuid"
},
"account_id": {
"type": [
"string",
"null"
],
"format": "uuid",
"description": "Saved account the session warms."
},
"bundle_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"order_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"source": {
"type": "string",
"enum": [
"bundle",
"rewarm"
]
},
"platform": {
"type": "string",
"enum": [
"tiktok",
"instagram"
]
},
"terms_total": {
"type": "integer",
"minimum": 3,
"maximum": 30
},
"search_terms": {
"type": "array",
"items": {
"type": "string"
}
},
"credits_cost": {
"type": "integer"
},
"started_at": {
"type": [
"string",
"null"
],
"format": "date-time"
}
}
},
"example_payload": {
"session_id": "6a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"account_id": "7c9e0f1a-2b3c-4d5e-8f6a-1b2c3d4e5f60",
"bundle_id": "9f3a7b2e-1c4d-4e8f-a5b6-7d9e0f1a2b3c",
"order_id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
"source": "rewarm",
"platform": "tiktok",
"terms_total": 6,
"search_terms": [
"healthy meal prep",
"high protein recipes",
"meal prep containers",
"quick healthy dinner",
"macro friendly meals",
"budget meal prep"
],
"credits_cost": 18,
"started_at": "2026-07-10T12:00:00Z"
}
},
{
"type": "warming.term_verified",
"category": "warming",
"availability": "emitted",
"description": "One advanced-warming search term was completed and its screen recording passed verification.",
"when": "Emitted after the manager's recording for a term is verified. The payload includes the client-facing per-term report (videos watched, likes, saves, comment, sample content, proof video link).",
"payload_schema": {
"type": "object",
"required": [
"session_id",
"task_id",
"term",
"report"
],
"properties": {
"session_id": {
"type": "string",
"format": "uuid"
},
"task_id": {
"type": "string",
"format": "uuid"
},
"term": {
"type": "string"
},
"report": {
"type": "object",
"description": "Client-facing per-term warming report, built after the term's screen recording is verified.",
"required": [
"term",
"day_index",
"verified_at"
],
"properties": {
"term": {
"type": "string"
},
"day_index": {
"type": "integer",
"minimum": 1,
"maximum": 3
},
"verified_at": {
"type": "string",
"format": "date-time"
},
"videos_watched": {
"type": "integer"
},
"likes": {
"type": "integer"
},
"saves": {
"type": "integer"
},
"comments": {
"type": "integer"
},
"keywords_seen": {
"type": "array",
"items": {
"type": "string"
}
},
"sample_videos": {
"type": "array",
"items": {
"type": "object",
"properties": {
"description": {
"type": "string"
},
"creator": {
"type": "string"
}
}
}
},
"proof_video_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"summary": {
"type": "string"
}
}
}
}
},
"example_payload": {
"session_id": "6a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"task_id": "0f1e2d3c-4b5a-4697-8877-665544332211",
"term": "healthy meal prep",
"report": {
"term": "healthy meal prep",
"day_index": 1,
"verified_at": "2026-07-10T14:05:00Z",
"videos_watched": 15,
"likes": 5,
"saves": 5,
"comments": 1,
"keywords_seen": [
"meal prep",
"high protein",
"recipes"
],
"sample_videos": [
{
"description": "5 high-protein lunches for the week",
"creator": "@prepqueen"
}
],
"proof_video_url": "https://media.tokportal.com/warming/session/task/recording.mp4",
"summary": "Searched \"healthy meal prep\" and engaged with the top results. Watched the videos through, liked and saved several, and left a comment."
}
}
},
{
"type": "warming.session_completed",
"category": "warming",
"availability": "emitted",
"description": "An advanced warming session finished and every search term was verified.",
"when": "Emitted when the last term of a session is verified. The payload includes the aggregated session report with per-term details and engagement totals.",
"payload_schema": {
"type": "object",
"required": [
"session_id",
"report"
],
"properties": {
"session_id": {
"type": "string",
"format": "uuid"
},
"report": {
"type": "object",
"description": "Aggregated client-facing report for the whole warming session, built when the session completes.",
"required": [
"terms_total",
"terms_verified",
"totals"
],
"properties": {
"terms_total": {
"type": "integer"
},
"terms_verified": {
"type": "integer"
},
"terms_expired": {
"type": "integer"
},
"totals": {
"type": "object",
"properties": {
"videos_watched": {
"type": "integer"
},
"likes": {
"type": "integer"
},
"saves": {
"type": "integer"
},
"comments": {
"type": "integer"
}
}
},
"terms": {
"type": "array",
"items": {
"type": "object",
"description": "Client-facing per-term warming report, built after the term's screen recording is verified.",
"required": [
"term",
"day_index",
"verified_at"
],
"properties": {
"term": {
"type": "string"
},
"day_index": {
"type": "integer",
"minimum": 1,
"maximum": 3
},
"verified_at": {
"type": "string",
"format": "date-time"
},
"videos_watched": {
"type": "integer"
},
"likes": {
"type": "integer"
},
"saves": {
"type": "integer"
},
"comments": {
"type": "integer"
},
"keywords_seen": {
"type": "array",
"items": {
"type": "string"
}
},
"sample_videos": {
"type": "array",
"items": {
"type": "object",
"properties": {
"description": {
"type": "string"
},
"creator": {
"type": "string"
}
}
}
},
"proof_video_url": {
"type": [
"string",
"null"
],
"format": "uri"
},
"summary": {
"type": "string"
}
}
}
},
"started_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"completed_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"summary": {
"type": "string"
}
}
}
}
},
"example_payload": {
"session_id": "6a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
"report": {
"terms_total": 6,
"terms_verified": 6,
"terms_expired": 0,
"totals": {
"videos_watched": 91,
"likes": 31,
"saves": 30,
"comments": 6
},
"terms": [
{
"term": "healthy meal prep",
"day_index": 1,
"verified_at": "2026-07-10T14:05:00Z",
"videos_watched": 15,
"likes": 5,
"saves": 5,
"comments": 1,
"keywords_seen": [
"meal prep",
"high protein",
"recipes"
],
"sample_videos": [
{
"description": "5 high-protein lunches for the week",
"creator": "@prepqueen"
}
],
"proof_video_url": "https://media.tokportal.com/warming/session/task/recording.mp4",
"summary": "Searched \"healthy meal prep\" and engaged with the top results. Watched the videos through, liked and saved several, and left a comment."
}
],
"started_at": "2026-07-10T12:00:00Z",
"completed_at": "2026-07-13T09:30:00Z",
"summary": "Warmed the account over 3 days across 6 search terms: 91 videos watched, 31 likes, 30 saves, and 6 comments posted."
}
}
},
{
"type": "subscription.renewed",
"category": "subscription",
"availability": "emitted",
"description": "TokPortal Coverage renewed for another 30-day period.",
"when": "Emitted after the automatic 25-credit renewal debit succeeds.",
"payload_schema": {
"type": "object",
"required": [
"subscription_id",
"saved_account_id"
],
"properties": {
"product": {
"type": [
"string",
"null"
],
"enum": [
"tokportal_coverage",
null
]
},
"subscription_id": {
"type": "string",
"format": "uuid"
},
"saved_account_id": {
"type": "string",
"format": "uuid"
},
"previous_status": {
"type": [
"string",
"null"
]
},
"period_start": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"period_end": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"current_period_start": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"current_period_end": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"credits_charged": {
"type": "integer",
"minimum": 0
},
"unpaid_periods_paid": {
"type": "integer",
"minimum": 0
},
"reactivation_was_free": {
"type": "boolean"
},
"period_rate_credits": {
"type": "integer",
"minimum": 0
},
"lapsed_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"cancelled_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"reactivation_requires_current_period": {
"type": "boolean",
"deprecated": true,
"description": "Deprecated compatibility field. Always false."
},
"reactivation_may_be_free_until": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"resumed_tasks": {
"type": [
"object",
"null"
]
},
"reason": {
"type": [
"string",
"null"
]
},
"credit_transaction_id": {
"type": [
"string",
"null"
],
"format": "uuid"
}
}
},
"example_payload": {
"subscription_id": "11111111-2222-4333-8444-555555555555",
"saved_account_id": "7c9e0f1a-2b3c-4d5e-8f6a-1b2c3d4e5f60",
"period_start": "2026-09-10T11:00:00Z",
"period_end": "2026-10-10T11:00:00Z",
"credits_charged": 25,
"credit_transaction_id": "22222222-3333-4444-8555-666666666666"
}
},
{
"type": "subscription.lapsed",
"category": "subscription",
"availability": "emitted",
"description": "TokPortal Coverage paused because its automatic renewal could not be paid.",
"when": "Emitted when the automatic renewal finds an insufficient credit balance.",
"payload_schema": {
"type": "object",
"required": [
"subscription_id",
"saved_account_id"
],
"properties": {
"product": {
"type": [
"string",
"null"
],
"enum": [
"tokportal_coverage",
null
]
},
"subscription_id": {
"type": "string",
"format": "uuid"
},
"saved_account_id": {
"type": "string",
"format": "uuid"
},
"previous_status": {
"type": [
"string",
"null"
]
},
"period_start": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"period_end": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"current_period_start": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"current_period_end": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"credits_charged": {
"type": "integer",
"minimum": 0
},
"unpaid_periods_paid": {
"type": "integer",
"minimum": 0
},
"reactivation_was_free": {
"type": "boolean"
},
"period_rate_credits": {
"type": "integer",
"minimum": 0
},
"lapsed_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"cancelled_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"reactivation_requires_current_period": {
"type": "boolean",
"deprecated": true,
"description": "Deprecated compatibility field. Always false."
},
"reactivation_may_be_free_until": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"resumed_tasks": {
"type": [
"object",
"null"
]
},
"reason": {
"type": [
"string",
"null"
]
},
"credit_transaction_id": {
"type": [
"string",
"null"
],
"format": "uuid"
}
}
},
"example_payload": {
"subscription_id": "11111111-2222-4333-8444-555555555555",
"saved_account_id": "7c9e0f1a-2b3c-4d5e-8f6a-1b2c3d4e5f60",
"period_start": "2026-09-10T11:00:00Z",
"period_end": "2026-10-10T11:00:00Z",
"lapsed_at": "2026-09-10T11:00:02Z",
"reason": "insufficient_credits"
}
},
{
"type": "subscription.cancelled",
"category": "subscription",
"availability": "emitted",
"description": "TokPortal Coverage was paused manually for an account.",
"when": "Committed atomically when the client pauses coverage, then delivered asynchronously with retries. Current tasks are withheld and new tasks are blocked until reactivation; the fresh quote may be free while a paid or included period remains.",
"payload_schema": {
"type": "object",
"required": [
"subscription_id",
"saved_account_id"
],
"properties": {
"product": {
"type": [
"string",
"null"
],
"enum": [
"tokportal_coverage",
null
]
},
"subscription_id": {
"type": "string",
"format": "uuid"
},
"saved_account_id": {
"type": "string",
"format": "uuid"
},
"previous_status": {
"type": [
"string",
"null"
]
},
"period_start": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"period_end": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"current_period_start": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"current_period_end": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"credits_charged": {
"type": "integer",
"minimum": 0
},
"unpaid_periods_paid": {
"type": "integer",
"minimum": 0
},
"reactivation_was_free": {
"type": "boolean"
},
"period_rate_credits": {
"type": "integer",
"minimum": 0
},
"lapsed_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"cancelled_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"reactivation_requires_current_period": {
"type": "boolean",
"deprecated": true,
"description": "Deprecated compatibility field. Always false."
},
"reactivation_may_be_free_until": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"resumed_tasks": {
"type": [
"object",
"null"
]
},
"reason": {
"type": [
"string",
"null"
]
},
"credit_transaction_id": {
"type": [
"string",
"null"
],
"format": "uuid"
}
}
},
"example_payload": {
"subscription_id": "11111111-2222-4333-8444-555555555555",
"saved_account_id": "7c9e0f1a-2b3c-4d5e-8f6a-1b2c3d4e5f60",
"cancelled_at": "2026-09-18T11:00:00Z",
"current_period_end": "2026-10-10T11:00:00Z",
"reactivation_requires_current_period": false,
"reactivation_may_be_free_until": "2026-10-10T11:00:00Z",
"reason": "cancelled_by_client"
}
},
{
"type": "subscription.reactivated",
"category": "subscription",
"availability": "emitted",
"description": "Paused TokPortal Coverage was reactivated atomically.",
"when": "Committed atomically when the quote snapshot is confirmed and Coverage resumes, then delivered asynchronously with retries. credits_charged is zero and credit_transaction_id is null when the current billing period was already paid or included.",
"payload_schema": {
"type": "object",
"required": [
"subscription_id",
"saved_account_id"
],
"properties": {
"product": {
"type": [
"string",
"null"
],
"enum": [
"tokportal_coverage",
null
]
},
"subscription_id": {
"type": "string",
"format": "uuid"
},
"saved_account_id": {
"type": "string",
"format": "uuid"
},
"previous_status": {
"type": [
"string",
"null"
]
},
"period_start": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"period_end": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"current_period_start": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"current_period_end": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"credits_charged": {
"type": "integer",
"minimum": 0
},
"unpaid_periods_paid": {
"type": "integer",
"minimum": 0
},
"reactivation_was_free": {
"type": "boolean"
},
"period_rate_credits": {
"type": "integer",
"minimum": 0
},
"lapsed_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"cancelled_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"reactivation_requires_current_period": {
"type": "boolean",
"deprecated": true,
"description": "Deprecated compatibility field. Always false."
},
"reactivation_may_be_free_until": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"resumed_tasks": {
"type": [
"object",
"null"
]
},
"reason": {
"type": [
"string",
"null"
]
},
"credit_transaction_id": {
"type": [
"string",
"null"
],
"format": "uuid"
}
}
},
"example_payload": {
"subscription_id": "11111111-2222-4333-8444-555555555555",
"saved_account_id": "7c9e0f1a-2b3c-4d5e-8f6a-1b2c3d4e5f60",
"credits_charged": 50,
"unpaid_periods_paid": 2,
"reactivation_was_free": false,
"period_rate_credits": 25,
"current_period_start": "2026-10-10T11:00:00Z",
"current_period_end": "2026-11-09T11:00:00Z",
"credit_transaction_id": "22222222-3333-4444-8555-666666666666"
}
},
{
"type": "subscription.ended",
"category": "subscription",
"availability": "emitted",
"description": "TokPortal Coverage ended permanently after a confirmed banned-account refund or credit-restoration resolution.",
"when": "Emitted after staff completes the eligible refund or credit-restoration resolution for a confirmed banned account. No future renewal or reactivation is possible.",
"payload_schema": {
"type": "object",
"required": [
"product",
"subscription_id",
"saved_account_id",
"status",
"ended_at",
"ended_reason",
"credits_restored",
"unpaid_periods_voided"
],
"properties": {
"product": {
"type": "string",
"enum": [
"tokportal_coverage"
]
},
"subscription_id": {
"type": "string",
"format": "uuid"
},
"saved_account_id": {
"type": "string",
"format": "uuid"
},
"previous_status": {
"type": [
"string",
"null"
]
},
"status": {
"type": "string",
"enum": [
"ended_ban"
]
},
"ended_at": {
"type": "string",
"format": "date-time"
},
"ended_reason": {
"type": [
"string",
"null"
]
},
"appeal_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"credits_restored": {
"type": "integer",
"minimum": 0
},
"unpaid_periods_voided": {
"type": "integer",
"minimum": 0
}
}
},
"example_payload": {
"product": "tokportal_coverage",
"subscription_id": "11111111-2222-4333-8444-555555555555",
"saved_account_id": "7c9e0f1a-2b3c-4d5e-8f6a-1b2c3d4e5f60",
"previous_status": "active",
"status": "ended_ban",
"ended_at": "2026-09-18T11:00:00Z",
"ended_reason": "eligible_platform_ban_refunded",
"appeal_id": "33333333-4444-4555-8666-777777777777",
"credits_restored": 57,
"unpaid_periods_voided": 0
}
},
{
"type": "account.revealed",
"category": "account",
"availability": "emitted",
"description": "The first credential or verification-code reveal was recorded for the account.",
"when": "Emitted once after the first successful reveal. Under the managed reveal policy, TokPortal Coverage ends permanently; a prior-policy reveal reports management_ended as false.",
"payload_schema": {
"type": "object",
"required": [
"saved_account_id",
"revealed_at",
"credits_charged",
"management_ended"
],
"properties": {
"saved_account_id": {
"type": "string",
"format": "uuid"
},
"revealed_at": {
"type": "string",
"format": "date-time"
},
"credits_charged": {
"type": "integer",
"minimum": 0
},
"management_ended": {
"type": "boolean"
}
}
},
"example_payload": {
"saved_account_id": "7c9e0f1a-2b3c-4d5e-8f6a-1b2c3d4e5f60",
"revealed_at": "2026-08-14T11:05:00Z",
"credits_charged": 150,
"management_ended": true
}
},
{
"type": "credits.restored",
"category": "credits",
"availability": "emitted",
"description": "Credits were restored after an eligible managed-account ban.",
"when": "Emitted after the staff ban resolution restores eligible credits with a 60-day expiry.",
"payload_schema": {
"type": "object",
"required": [
"saved_account_id",
"credits_restored",
"expires_at"
],
"properties": {
"saved_account_id": {
"type": "string",
"format": "uuid"
},
"appeal_id": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"credits_restored": {
"type": "integer",
"minimum": 1
},
"expires_at": {
"type": "string",
"format": "date-time"
},
"credit_transaction_id": {
"type": [
"string",
"null"
],
"format": "uuid"
}
}
},
"example_payload": {
"saved_account_id": "7c9e0f1a-2b3c-4d5e-8f6a-1b2c3d4e5f60",
"appeal_id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d",
"credits_restored": 42,
"expires_at": "2026-10-13T10:00:00Z",
"credit_transaction_id": "22222222-3333-4444-8555-666666666666"
}
}
],
"envelope": {
"id": "evt_0123456789abcdef0123456789abcdef",
"type": "bundle.published",
"api_version": "2026-05-25",
"created_at": "2026-06-01T12:00:00.000Z",
"data": {}
},
"delivery": {
"method": "POST",
"content_type": "application/json",
"timeout_ms": 8000,
"user_agent": "TokPortal-Webhooks/1.0",
"headers": [
"TokPortal-Event-Id",
"TokPortal-Event-Type",
"TokPortal-Signature"
]
},
"signature": {
"header": "TokPortal-Signature",
"scheme": "t={unix_timestamp},v1={hmac_sha256}",
"signed_payload": "{timestamp}.{raw_body}",
"algorithm": "HMAC-SHA256",
"default_tolerance_seconds": 300
}
}
}Changes
No recorded changes to this operation across all 1 revision of this API.