# Get ban alerts via webhooks

Source: https://developers.tokportal.com/agents/for/ban-webhooks/
Markdown: https://developers.tokportal.com/agents/for/ban-webhooks.md

From any MCP-capable agent, 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.

## 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 any MCP-capable agent 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.

## 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.

## Pick your agent

- [Get ban alerts via webhooks with Claude](https://developers.tokportal.com/agents/claude/ban-webhooks) — Anthropic's assistant on claude.ai, the mobile apps and Claude Desktop, with custom MCP connectors.
- [Get ban alerts via webhooks with Claude Code](https://developers.tokportal.com/agents/claude-code/ban-webhooks) — Anthropic's terminal coding agent; MCP servers are added with `claude mcp add` and used in any session.
- [Get ban alerts via webhooks with ChatGPT](https://developers.tokportal.com/agents/chatgpt/ban-webhooks) — OpenAI's assistant; plans with developer mode can add remote MCP servers as custom connectors.
- [Get ban alerts via webhooks with OpenAI Codex](https://developers.tokportal.com/agents/codex/ban-webhooks) — OpenAI's coding agent (Codex CLI and IDE extension); MCP servers live in `~/.codex/config.toml`.
- [Get ban alerts via webhooks with Cursor](https://developers.tokportal.com/agents/cursor/ban-webhooks) — AI code editor with an agent mode; MCP servers are configured in `.cursor/mcp.json` or via a one-click deeplink.
- [Get ban alerts via webhooks with Windsurf](https://developers.tokportal.com/agents/windsurf/ban-webhooks) — Codeium's agentic IDE (Cascade); MCP servers are declared in `~/.codeium/windsurf/mcp_config.json`.
- [Get ban alerts via webhooks with Cline](https://developers.tokportal.com/agents/cline/ban-webhooks) — Open-source autonomous coding agent for VS Code with an MCP marketplace and per-tool approval.
- [Get ban alerts via webhooks with OpenClaw](https://developers.tokportal.com/agents/openclaw/ban-webhooks) — Open-source autonomous agent runtime with a skills registry (ClawHub); TokPortal ships as a first-party skill.
- [Get ban alerts via webhooks with Hermes Agent](https://developers.tokportal.com/agents/hermes-agent/ban-webhooks) — Nous Research's open-source agent runtime; MCP servers are declared under `mcp_servers` in `~/.hermes/config.yaml`.
- [Get ban alerts via webhooks with Gemini CLI](https://developers.tokportal.com/agents/gemini-cli/ban-webhooks) — Google's open-source terminal agent for Gemini; MCP servers via `gemini mcp add` or `~/.gemini/settings.json`, plus extensions.
- [Get ban alerts via webhooks with Goose](https://developers.tokportal.com/agents/goose/ban-webhooks) — Block's open-source local agent; remote MCP servers are added as extensions (Streaming HTTP) or via a `goose://` deeplink.
- [Get ban alerts via webhooks with Perplexity](https://developers.tokportal.com/agents/perplexity/ban-webhooks) — Answer engine with custom MCP connectors on paid plans; good for read-only research over your TokPortal data.
- [Get ban alerts via webhooks with Microsoft Copilot Studio](https://developers.tokportal.com/agents/copilot-studio/ban-webhooks) — Microsoft's low-code agent builder; MCP servers are added as tools through the MCP onboarding wizard (Streamable transport).
- [Get ban alerts via webhooks with Factory Droid](https://developers.tokportal.com/agents/factory-droid/ban-webhooks) — Factory's software-engineering agent (`droid` CLI); HTTP MCP servers are added with `droid mcp add`.
- [Get ban alerts via webhooks with n8n](https://developers.tokportal.com/agents/n8n/ban-webhooks) — Open-source workflow automation; use the built-in MCP Client Tool node with an AI Agent, or the community node `n8n-nodes-tokportal` for deterministic steps.
- [Get ban alerts via webhooks with Make](https://developers.tokportal.com/agents/make/ban-webhooks) — Visual automation platform (ex-Integromat); call TokPortal from HTTP modules with `X-API-Key`, or from Make's MCP Client module where available.
- [Get ban alerts via webhooks with Zapier](https://developers.tokportal.com/agents/zapier/ban-webhooks) — Automation platform; today TokPortal is used via Webhooks by Zapier (REST) — a native TokPortal app is coming.
- [Get ban alerts via webhooks with Pipedream](https://developers.tokportal.com/agents/pipedream/ban-webhooks) — Serverless integration platform for developers; call TokPortal from a Node.js/Python code step or the HTTP action, and receive webhooks on an HTTP trigger.
- [Get ban alerts via webhooks with Dify](https://developers.tokportal.com/agents/dify/ban-webhooks) — Open-source LLM app platform; MCP servers are registered under Tools → MCP and used by Agent nodes and Agent apps.
- [Get ban alerts via webhooks with Flowise](https://developers.tokportal.com/agents/flowise/ban-webhooks) — Open-source visual builder for LLM flows; the Custom MCP node connects any Streamable HTTP server to Agentflow / tool agents.
- [Get ban alerts via webhooks with Langflow](https://developers.tokportal.com/agents/langflow/ban-webhooks) — Open-source visual framework for agents; the MCP Tools component connects to servers registered in Settings → MCP Servers.
- [Get ban alerts via webhooks with CrewAI](https://developers.tokportal.com/agents/crewai/ban-webhooks) — Python multi-agent framework; `MCPServerAdapter` from `crewai-tools` turns any MCP server into agent tools.
- [Get ban alerts via webhooks with LangChain](https://developers.tokportal.com/agents/langchain/ban-webhooks) — LangChain / LangGraph agents load MCP tools with `langchain-mcp-adapters` (`MultiServerMCPClient`).
- [Get ban alerts via webhooks with Vercel AI SDK](https://developers.tokportal.com/agents/vercel-ai-sdk/ban-webhooks) — TypeScript toolkit for AI apps; the MCP client (`@ai-sdk/mcp`, formerly `experimental_createMCPClient` in `ai`) turns TokPortal tools into `generateText`/`streamText` tools.
- [Get ban alerts via webhooks with Mastra](https://developers.tokportal.com/agents/mastra/ban-webhooks) — TypeScript agent framework; `MCPClient` from `@mastra/mcp` connects HTTP or stdio MCP servers and hands their tools to an `Agent`.

## 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)
- [All agents](https://developers.tokportal.com/agents)