# Get ban alerts via webhooks with Microsoft Copilot Studio Source: https://developers.tokportal.com/agents/copilot-studio/ban-webhooks/ Markdown: https://developers.tokportal.com/agents/copilot-studio/ban-webhooks.md From Microsoft Copilot Studio, 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 Microsoft Copilot Studio Microsoft Copilot Studio is a workflow / low-code platform: Microsoft's low-code agent builder; MCP servers are added as tools through the MCP onboarding wizard (Streamable transport). In your agent: **Tools → Add a tool → New tool → Model Context Protocol**, then: - **Server name**: `TokPortal` - **Server description**: `Create, warm and operate TikTok/Instagram accounts; schedule videos; read analytics and ban status.` - **Server URL**: `https://app.tokportal.com/api/ext/mcp` - **Authentication**: **OAuth 2.0 → Dynamic discovery** (TokPortal supports discovery + dynamic client registration), or **API key → Header** named `X-API-Key` with your `sk_...` key. Select **Create**, create the connection, then **Add to agent**. Generative orchestration must be enabled. Snippet status: **verified** against Microsoft Copilot Studio's documentation ([source](https://learn.microsoft.com/en-us/microsoft-copilot-studio/mcp-add-existing-server-to-agent)). Once connected, sanity-check the setup with a read-only call: "What is my TokPortal credit balance?" should trigger `tokportal_get_credit_balance`. GET requests and dry-run writes do not spend credits. ## Try the workflow without spending For this trial, use the remote MCP endpoint `https://app.tokportal.com/api/ext/mcp`, local `tokportal-mcp` **1.15.1 or later**, or the REST API. Upgrade and restart an older local server first. Version 1.15.0 does not forward the dry-run header; do not use its write tools for a simulation. If you cannot verify the installed local version, use the remote endpoint or REST. Use the [sandbox](https://developers.tokportal.com/sandbox) for the first attempt. MCP write tools accept `dry_run: true` as a top-level argument, beside `body`; REST writes accept the `X-TokPortal-Dry-Run: true` header. Keep your usual authentication and scopes. Each simulated write validates the request and returns `credits_would_charge` with `credits_charged: 0`. Nothing is created or published. Simulated IDs start with `00000000-0000-4000-8000-`. Use them only in later dry-run writes. GET requests read real data, so skip publish-readiness checks and polling for synthetic IDs. Simulations have no cross-call memory and upload URLs are placeholders: do not upload files to them. To run for real, review the returned price and confirm **before the first live write**. Bundle creation charges credits immediately; publishing hands the order to a manager. Repeat creation without dry-run mode and use the new real IDs for configuration and publishing. A synthetic ID cannot be reused in a live request. ## 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 Microsoft Copilot Studio 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=,v1=`) 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 Microsoft Copilot Studio In Microsoft Copilot Studio the same sequence becomes nodes/steps: either an AI Agent step with the TokPortal tools and the prompt below as its instruction, or one deterministic step per tool. Set `dry_run: true` on MCP write tools, or `X-TokPortal-Dry-Run: true` on HTTP write steps. Map `data.bundle_id` from bundle creation into later simulated write steps; poll only after a real run. **Tool sequence** 1. `tokportal_list_webhook_events` — Catalogue of event names and payload contract. 2. `tokportal_create_webhook_endpoint` — `url`, `events: ["account.ban_appeal.submitted","account.banned","account.ban_resolution.decided","credits.restored"]`. 3. `tokportal_test_webhook_endpoint` — Sends `webhook.test` to validate your receiver and signature check. 4. `tokportal_get_webhook_endpoint` — Endpoint details incl. signing secret. 5. `tokportal_list_webhook_deliveries` — Delivery log per endpoint (status, attempts). 6. `tokportal_retry_webhook_delivery` — Replay a failed delivery by `delivery_id`. 7. `tokportal_list_account_bans` — Source of truth: `status`, `resolution`, `since`, `include_screenshots`. 8. `tokportal_list_accounts` — `banned=true|false` filter and the `ban_appeal` block per account. **Prompt to paste** ```text Evaluate this workflow in the TokPortal sandbox only. Use the remote MCP endpoint https://app.tokportal.com/api/ext/mcp or local tokportal-mcp 1.15.1 or later for write tools. Verify the installed local version before using its write tools. Version 1.15.0 is unsafe for simulations. If the local version is older or unknown, use the remote endpoint or authenticated REST requests with X-TokPortal-Dry-Run: true instead. For every non-GET MCP tool call, set dry_run: true as a top-level boolean beside body. For every REST write in a workflow, send the X-TokPortal-Dry-Run: true header. Use normal read tools for existing real objects. Do not GET or poll synthetic IDs, and do not upload files to simulated upload URLs. Simulated objects have no cross-call memory. Show credits_would_charge and verify credits_charged is 0 for each simulated write. Do not execute any live write. Ask for my explicit GO before the first real write, including bundle creation, which charges immediately. After GO, repeat creation without dry_run and use the new real IDs; never reuse synthetic IDs in live requests. 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, simulate a test delivery (no webhook is sent), then show me list_account_bans since 2026-08-01 grouped by status and resolution. ``` Test in the Copilot Studio test pane; the orchestrator picks `tokportal_*` tools from the server description, so keep the description specific. **REST equivalent** (write requests below are simulations; GET requests read existing real data) ```bash curl -X POST -H "X-TokPortal-Dry-Run: true" 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 -H "X-TokPortal-Dry-Run: true" 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](https://developers.tokportal.com/webhooks). ## 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](https://developers.tokportal.com/api-reference) · [openapi.json](https://developers.tokportal.com/openapi.json). ## Example configurations **Ban-only endpoint** ```json {"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** ```json {"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)** ```json {"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](https://developers.tokportal.com/credits) and [Bans & Appeals](https://developers.tokportal.com/bans-and-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](https://developers.tiktok.com/doc/content-posting-api-reference-direct-post), [TikTok Content Posting API – Get started](https://developers.tiktok.com/doc/content-posting-api-get-started), [Instagram Platform – Content Publishing](https://developers.facebook.com/docs/instagram-platform/content-publishing). ## FAQ ### 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`. ### How do I verify a delivery is genuine? Compute HMAC SHA-256 of the raw request body with the endpoint secret and compare with `v1` in `TokPortal-Signature`; reject stale `t` values. The Node SDK's `verifyWebhookSignature` does this. ### 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=…`. ### 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. ## Related - [Bans & appeals](https://developers.tokportal.com/bans-and-appeals) - [Webhooks](https://developers.tokportal.com/webhooks) - [Saved accounts](https://developers.tokportal.com/saved-accounts) - [Agency multi-client](https://developers.tokportal.com/use-cases/industry/agency-multi-client-management) - [MCP server](https://developers.tokportal.com/mcp) ## Also works with - [Get ban alerts via webhooks with Zapier](https://developers.tokportal.com/agents/zapier/ban-webhooks) - [Get ban alerts via webhooks with Pipedream](https://developers.tokportal.com/agents/pipedream/ban-webhooks) - [Get ban alerts via webhooks with Dify](https://developers.tokportal.com/agents/dify/ban-webhooks) - [Get ban alerts via webhooks with Flowise](https://developers.tokportal.com/agents/flowise/ban-webhooks) - [Get ban alerts via webhooks with Langflow](https://developers.tokportal.com/agents/langflow/ban-webhooks) - [Get ban alerts via webhooks with CrewAI](https://developers.tokportal.com/agents/crewai/ban-webhooks) [All 25 agents for "Get ban alerts via webhooks"](https://developers.tokportal.com/agents/for/ban-webhooks) ## Other jobs with Microsoft Copilot Studio - [Create TikTok accounts with Microsoft Copilot Studio](https://developers.tokportal.com/agents/copilot-studio/create-tiktok-accounts) - [Post 100 TikTok videos a day with Microsoft Copilot Studio](https://developers.tokportal.com/agents/copilot-studio/post-100-videos-a-day) - [Run US TikTok accounts from abroad with Microsoft Copilot Studio](https://developers.tokportal.com/agents/copilot-studio/us-tiktok-accounts-from-abroad) - [Warm TikTok & Instagram accounts with Microsoft Copilot Studio](https://developers.tokportal.com/agents/copilot-studio/warm-accounts) - [Run a faceless TikTok channel with Microsoft Copilot Studio](https://developers.tokportal.com/agents/copilot-studio/faceless-channel) - [Seed UGC across many accounts with Microsoft Copilot Studio](https://developers.tokportal.com/agents/copilot-studio/ugc-seeding) - [Seed a music sound on TikTok with Microsoft Copilot Studio](https://developers.tokportal.com/agents/copilot-studio/music-sound-seeding) - [Launch an app with persona accounts with Microsoft Copilot Studio](https://developers.tokportal.com/agents/copilot-studio/app-persona-launch) - [Run multi-client agency operations with Microsoft Copilot Studio](https://developers.tokportal.com/agents/copilot-studio/agency-multi-client) - [Pull analytics across all accounts with Microsoft Copilot Studio](https://developers.tokportal.com/agents/copilot-studio/analytics-multi-account) - [Create Instagram accounts with Microsoft Copilot Studio](https://developers.tokportal.com/agents/copilot-studio/create-instagram-accounts)