TokPortal Webhooks: Real-Time Event Notifications for Social Media Automation

You scheduled a video. Now what? You're either sitting there refreshing a dashboard, writing a polling loop that hammers an API every 30 seconds, or just hoping it worked. None of those are acceptable when you're running campaigns across 50 accounts in 12 countries.

Real automation doesn't ask "did it happen yet?" — it gets told the moment it does. That's the entire value of webhooks, and it's why TokPortal built a comprehensive webhook system into its REST API. Every significant event in your account's lifecycle — creation, warming, video upload, post confirmation, errors — fires a webhook payload to your endpoint in real time. Your pipeline reacts instantly, without wasting a single API call.

This article covers everything: what TokPortal webhook events exist, how to configure them, what the payloads look like, and how to wire them into production-grade automation with tools like n8n, Make.com, or your own backend.

When you're managing one TikTok account manually, polling works fine. You check the app, you see the video posted, you move on. But when you're operating programmatic infrastructure — dozens of accounts, automated warming sequences, scheduled content calendars, CRM sync triggers — polling creates compounding problems.

Every poll is a wasted request. Every 30-second delay is a downstream bottleneck. If your video upload fails and you find out 10 minutes later, you've already missed your posting window. If your account warming completes and you don't know for an hour, the next step in your sequence is sitting idle.

Webhooks invert the model: instead of your system asking "are we there yet?" every few seconds, TokPortal tells your system exactly when something changes, what changed, and what the current state is. Your automation becomes event-driven, which means it's faster, cheaper to run, and easier to debug.

TokPortal webhooks are organized around the lifecycle of two core objects: accounts (bundles) and videos. Here's what fires, and when.

Every webhook TokPortal fires follows a consistent JSON envelope structure. This matters enormously for building reliable consumers — you can parse every event type with the same base logic and then branch on the event field. The full payload schema is documented at developers.tokportal.com, but here's the anatomy of a typical event:

• event — The event type string (e.g. video.posted)
• timestamp — ISO 8601 UTC timestamp of when the event occurred on the device
• bundle_id — The unique identifier of the account this event belongs to
• platform — Either tiktok or instagram
• country — The country code of the physical device (e.g. US, GB, BR)
• data — Event-specific object containing relevant state, IDs, error codes, or metric snapshots
• signature — HMAC-SHA256 signature for verifying the payload came from TokPortal

Always verify the signature before processing. Any webhook consumer worth shipping in production validates the X-TokPortal-Signature header before touching the payload. The full verification guide lives in the API documentation.

The event map isn't theoretical — here are the concrete automation workflows that TokPortal users are running in production today.

When bundle.created fires, trigger warming automatically. When bundle.warming_completed fires, immediately schedule the first batch of videos. When bundle.warming_failed fires, alert your ops team and flag the bundle for review. This entire lifecycle runs without a human touching a dashboard. You can wire this in n8n with a webhook trigger node in under an hour.

A new product is marked as "launch-ready" in HubSpot. That triggers a workflow that calls the TokPortal API to schedule videos across 20 accounts. As each video.posted webhook arrives, a record is created in your CRM tagging which account posted, at what time, in which country. When video.analytics_updated fires 24 hours later, the CRM record updates with early performance data. Full attribution, zero manual work. Make.com handles the HubSpot-to-TokPortal bridge cleanly.

This is where things get genuinely interesting. TokPortal's MCP server lets AI agents like Claude autonomously manage campaigns. Webhooks are the feedback loop that makes this work: the agent posts a video, waits for the video.posted confirmation webhook, checks early analytics when video.analytics_updated fires, and decides whether to increase posting frequency or pull back — all without human intervention. The agent isn't guessing whether actions succeeded; it knows, because TokPortal told it.

Production campaigns fail silently when there's no error telemetry. With webhooks, video.post_failed and bundle.banned events flow into a Zapier workflow that fires a Slack alert, creates a Notion task for ops review, and automatically reroutes the scheduled content to a backup account in the same country. Recovery time drops from hours to seconds.

You don't need to build a custom webhook consumer from scratch to get started. TokPortal integrates with the major automation platforms that already have webhook handling built in:

• n8n — Use the Webhook node as your trigger. n8n's visual workflow builder makes it easy to branch on event type, transform payload data, and connect to any downstream service. Self-hostable if you need data residency.
• Make.com — The Custom Webhook module catches TokPortal events and feeds them into scenario flows. Strong choice for connecting to Google Sheets, Airtable, or Slack without writing code.
• Zapier — Catch Hook triggers let you receive TokPortal webhooks and fan out to 5,000+ connected apps. Best for teams already deep in the Zapier ecosystem.
• Custom backend — If you're building your own infrastructure, the full webhook spec at developers.tokportal.com covers everything: endpoint registration, payload schemas, retry logic, signature verification, and event filtering.

A webhook endpoint that doesn't validate signatures is a public endpoint that anyone can POST to with fake events. In a social distribution pipeline, a spoofed bundle.ready event could kick off warming on an account that doesn't exist, or a spoofed video.posted could mark content as published when it never went live. Three non-negotiable security steps:

1. Always verify HMAC-SHA256 signatures. TokPortal signs every payload with your webhook secret. Reject anything that doesn't match before processing.
2. Use HTTPS endpoints only. Never expose a webhook consumer over plain HTTP. TokPortal will reject non-HTTPS endpoint registrations.
3. Rate-limit and scope your endpoint. Your webhook consumer should only be reachable from TokPortal's published IP ranges (listed in the API docs). Anything else should return 403 before it touches your business logic.

Full security implementation guidance is available at developers.tokportal.com.