Get ban alerts via webhooks with CrewAI

Q: Which event should pause my scheduling?

`account.ban_appeal.submitted` — the account is already unavailable even though not yet confirmed banned. Resume on `account.ban_appeal.resolved` (accepted) or reassign content on `account.banned`.

Q: What if my endpoint was down for an hour?

TokPortal retries; check `list_webhook_deliveries` and call `retry_webhook_delivery` for anything still failed. Reconcile with `list_account_bans?since=…`.

Q: Can the agent tell me if I get a refund?

Yes — `account.ban_resolution.decided` carries `resolution` and `refund_credits`; `list_account_bans?resolution=refund` lists them; `credits.restored` fires when Coverage restores credits.

From CrewAI, ban visibility is one create_webhook_endpoint call subscribing to account.ban_appeal.submitted (the earliest signal — the manager filed a platform appeal and the account is unavailable), account.banned (confirmed) and account.ban_resolution.decided (TokPortal's commercial outcome: refund, remake or no_remake with a reason_code), plus list_account_bans as the pollable source of truth. Deliveries are signed (TokPortal-Signature, HMAC SHA-256) and retryable with retry_webhook_delivery. No official API tells you a third-party account was banned; here it is a first-class event.

Connect TokPortal to CrewAI

CrewAI is an agent framework (code): Python multi-agent framework; MCPServerAdapter from crewai-tools turns any MCP server into agent tools.

pip install "crewai-tools[mcp]"

from crewai import Agent, Task, Crew, Process
from crewai_tools import MCPServerAdapter

server_params = {
    "url": "https://app.tokportal.com/api/ext/mcp",
    "transport": "streamable-http",
    "headers": {"X-API-Key": "sk_..."},
}

with MCPServerAdapter(server_params) as tools:
    ops = Agent(
        role="Social ops",
        goal="Operate TikTok accounts through TokPortal tools.",
        backstory="Runs bundles, videos and analytics via the TokPortal MCP server.",
        tools=tools,
        verbose=True,
    )
    task = Task(
        description="Check the credit balance and list published bundles.",
        expected_output="A short report with balance and bundle ids.",
        agent=ops,
    )
    Crew(agents=[ops], tasks=[task], process=Process.sequential).kickoff()

Filter tools with tools["tokportal_get_credit_balance", "tokportal_list_bundles"] for read-only crews. (headers is passed through to the underlying MCP client; the CrewAI docs sample only shows url + transport.)

Snippet status: verified against CrewAI's documentation (source).

Once connected, sanity-check the setup with a read-only call — "What is my TokPortal credit balance?" should trigger tokportal_get_credit_balance. Every tool runs as your TokPortal account and spends your credits; read-only tools (get_*, list_*, export_*) never do.

How it works

The lifecycle is explicit. When a manager can no longer use an account and files an appeal with the platform, TokPortal emits account.ban_appeal.submitted — that is the moment to pause scheduling for that account in your systems. If the appeal succeeds, account.ban_appeal.resolved reports it and the account continues; if it fails or there is no appeal path, account.banned fires and the account's banned flag flips in list_accounts. Staff then decide the commercial outcome and account.ban_resolution.decided carries resolution (refund, remake, no_remake), a reason_code (e.g. tos_ban) and refund_credits; credits.restored fires if TokPortal Coverage restores credits. Bundles tied to a banned account are cancelled (bundle.cancelled).

From CrewAI the setup is: list_webhook_events to see the catalogue, create_webhook_endpoint with your url and the four events, test_webhook_endpoint to receive a webhook.test, and get_webhook_endpoint to copy the signing secret into your receiver. Verify TokPortal-Signature (t=<timestamp>,v1=<hex>) with the raw body — the Node SDK ships verifyWebhookSignature. If your endpoint was down, list_webhook_deliveries shows failed attempts and retry_webhook_delivery replays one.

For reporting and reconciliation, list_account_bans is the only source of truth: filter status (appeal_pending, appeal_accepted, appeal_refused, no_appeal_banned), resolution (refund, remake, no_remake, pending), since as a polling watermark, and include_screenshots=true for a signed 7-day evidence URL. Agents must report these values verbatim and never infer a ban from missing analytics or a not_found profile.

Run it from CrewAI

With CrewAI the sequence is driven by your code: give the agent the tools from the TokPortal MCP server and the prompt below as the user message (or split it into tasks). Log every tokportal_* call and its arguments in development — the tool list is large (91 tools), so consider filtering to the ones this job needs.

Tool sequence

tokportal_list_webhook_events — Catalogue of event names and payload contract.
tokportal_create_webhook_endpoint — url, events: ["account.ban_appeal.submitted","account.banned","account.ban_resolution.decided","credits.restored"].
tokportal_test_webhook_endpoint — Sends webhook.test to validate your receiver and signature check.
tokportal_get_webhook_endpoint — Endpoint details incl. signing secret.
tokportal_list_webhook_deliveries — Delivery log per endpoint (status, attempts).
tokportal_retry_webhook_delivery — Replay a failed delivery by delivery_id.
tokportal_list_account_bans — Source of truth: status, resolution, since, include_screenshots.
tokportal_list_accounts — banned=true|false filter and the ban_appeal block per account.

Prompt to paste

Use the TokPortal MCP tools. Create a webhook endpoint at https://hooks.example.com/tokportal for
account.ban_appeal.submitted, account.banned, account.ban_resolution.decided and credits.restored,
send a test delivery, then show me list_account_bans since 2026-08-01 grouped by status and resolution.

Run the script; each tokportal_* call appears in the verbose log with its arguments.

REST equivalent (same operations, X-API-Key header, base URL https://app.tokportal.com/api/ext)

curl -X POST https://app.tokportal.com/api/ext/webhooks \
  -H "X-API-Key: sk_..." -H "Content-Type: application/json" \
  -d '{"url":"https://hooks.example.com/tokportal","description":"Ban alerts",
       "events":["account.ban_appeal.submitted","account.banned","account.ban_resolution.decided","credits.restored"]}'

curl -X POST https://app.tokportal.com/api/ext/webhooks/ENDPOINT_ID/test -H "X-API-Key: sk_..."

# Poll as a backstop
curl "https://app.tokportal.com/api/ext/account-bans?since=2026-08-01T00:00:00Z&include_screenshots=true" -H "X-API-Key: sk_..."

Receiver (Node): verify TokPortal-Signature with the raw body before parsing — see Webhooks → Signature verification.

Key parameters

Parameter	Values	Notes
`events`	account.ban_appeal.submitted · account.banned · account.ban_appeal.resolved · account.ban_resolution.decided · credits.restored · bundle.cancelled	Up to 50 events per endpoint.
`url`	https URI ≤2000 chars	Must answer 2xx quickly; retries otherwise.
`TokPortal-Signature (header)`	t=,v1=	HMAC SHA-256 over the raw body; verify with the endpoint secret.
`status (list_account_bans)`	appeal_pending · appeal_accepted · appeal_refused · no_appeal_banned	Report verbatim.
`resolution`	refund · remake · no_remake · pending	Staff commercial outcome with reason_code and refund_credits.
`since`	ISO timestamp	updated_at watermark for polling.

Full schemas: OpenAPI reference · openapi.json.

Example configurations

Ban-only endpoint

{"url":"https://hooks.example.com/tokportal/bans","events":["account.ban_appeal.submitted","account.banned","account.ban_resolution.decided"],"description":"Ban alerts → Slack"}

Full lifecycle endpoint

{"url":"https://hooks.example.com/tokportal/all","events":["account.finalized","video.finalized","account.ban_appeal.submitted","account.banned","account.ban_resolution.decided","credits.restored","bundle.cancelled"]}

Example account.ban_resolution.decided payload (shape)

{"type":"account.ban_resolution.decided","data":{"account_id":"ACCOUNT_UUID","status":"appeal_refused","resolution":"remake","reason_code":"platform_policy","refund_credits":0}}

Credits

Webhooks are free. TokPortal Coverage (25 credits / 30 days per eligible saved account after the included first period) is what funds refund / remake outcomes and credits.restored; read the exact terms on Credits & Pricing and Bans & Appeals.

Why not the official API

Official APIs surface a ban only indirectly — calls start failing with token or permission errors on an account you own — and never for accounts operated by someone else. TokPortal's managers see the ban first, file the appeal, and the API turns each step into a signed event and a queryable record, dated 2026-08-16 in the changelog.

As of August 2026 the first-party routes look like this. TikTok's Content Posting API (Direct Post) requires each account owner to authorize your app with the video.publish scope, limits every user access token to 6 requests per minute, keeps all posts from unaudited apps in private viewing mode until TikTok audits the app, and enforces an unpublished daily post cap per user (spam_risk_too_many_posts) that integrators commonly report at roughly 15–25 posts per account per day. Meta's Instagram Content Publishing API allows 100 API-published posts per professional account in a 24-hour moving window and only for accounts you own and connect via OAuth. Neither creates accounts, warms them, or reports third-party bans. TokPortal is human-operated infrastructure: accounts created and run by managers in the target country, one X-API-Key for all of them, dated slots (max 3 per day per bundle) instead of per-account tokens.

Sources: TikTok Content Posting API – Direct Post, TikTok Content Posting API – Get started, Instagram Platform – Content Publishing.

Get ban alerts via webhooks with CrewAI

Connect TokPortal to CrewAI

How it works

Run it from CrewAI

Key parameters

Example configurations

Credits

Why not the official API

FAQ

Which event should pause my scheduling?

How do I verify a delivery is genuine?

What if my endpoint was down for an hour?

Can the agent tell me if I get a refund?

Also works with

Other jobs with CrewAI