What is a social media scheduling API webhook?
A social media scheduling API webhook is an automated callback sent to your system when a scheduled post reaches a defined publishing state. Your application gives the scheduling service a callback address, and the service sends an event when the job is accepted, published, rejected, delayed, or otherwise changed.
The webhook is a notification, not the post itself and not automatically proof that every user can see it. The useful event should include a stable post or job identifier, the connected account involved, the destination network, the event type, and the time recorded by the service. Your system can then update an internal job record, notify an operator, or trigger a retry review.
The key distinction is between transport and outcome. A callback can reach your server even when the destination network later removes, limits, or fails to display the post. A good implementation treats webhook data as the fastest signal and keeps a separate delivery check for uncertain cases. That distinction matters most when one piece of content is sent to many accounts and a single success label hides a partial failure.
In PostWharf, you register an https endpoint with POST /v1/webhooks and choose the events it receives, or take them all. The events are delivery.succeeded, delivery.retrying and delivery.failed for each network a post goes to, plus channel.token_expiring before an account's sign-in lapses and channel.disconnected when a channel is removed. A failure event carries the attempt number, the error and an action field naming what to do, such as reconnecting the account, so your system knows the next step rather than only that something went wrong.
For more context, read How to Choose a Social Tool That Proves Posts Went Live.
Should you use webhooks or polling for publishing updates?
Webhooks are usually the better first signal, while polling is the better fallback and reconciliation method. A webhook lets your system wait for a state change instead of repeatedly requesting the same job status, which reduces unnecessary traffic and shortens the time between an event and an operator action.
Polling remains useful when the provider has no webhook support, when a callback endpoint was temporarily unavailable, or when an event might have been missed. A practical design polls only jobs that are still unresolved or whose webhook history is incomplete. It should stop polling once a final state is confirmed, rather than checking every post forever.
The choice also depends on who owns the publishing layer. Direct network integrations may expose different event types and delivery guarantees. A scheduler API may normalize those events across networks, but its event model is the one your system must follow. Compare whether each option gives you stable identifiers, replay or recovery options, final delivery states, and enough account context to identify the affected channel. Fast notification without recoverability is not operational confidence.
PostWharf gives you both on every plan. Webhooks deliver the event as it happens, GET /v1/posts/:id returns a post with every delivery for polling, and GET /v1/events is a receipt feed carrying the same events, so a job whose webhook history is incomplete can be filled in from the feed rather than guessed at.
For more context, read Social Media Scheduler With a REST API: What to Check.
Which webhook events actually prove a post was delivered?
Only an event explicitly representing confirmed delivery should be treated as delivery proof, and even that proof has a defined scope. An accepted event usually means the publishing service received the job. A queued event means work remains. A published event may mean the service completed its submission, but it does not always mean the destination network displayed the post publicly.
Read the provider's event definitions before mapping any event to a green check mark. Separate states such as accepted, submitted, delivered, rejected, expired, and unknown when the provider exposes them. Store the original event type and source instead of reducing every positive event to “success.” That preserves evidence when an operator investigates a missing post.
Network behavior can also interrupt the chain after delivery. Moderation, account restrictions, processing delays, deleted content, and media checks can change what viewers see. A reliable dashboard therefore shows the strongest confirmed state, the last update time, and a link or platform identifier when available. Official network documentation should be checked because API capabilities, event meanings, and review rules can change.
PostWharf separates these states for each delivery. Every network on a post has its own status, so a leg that is still retrying never reads as published, and a post where one network refused reads as partial rather than published. A published delivery carries the URL of the post on the network, and published deliveries are checked again afterwards, so a post removed by moderation later stops reporting as live.
How should a webhook consumer handle duplicates and missed events?
A webhook consumer should be idempotent, because the same event may arrive more than once and an event may arrive after a retry. Use the provider's event identifier when one exists, or create a deduplication key from the job, account, event type, and event timestamp. Processing the same notification twice must not send a second alert, create a duplicate record, or trigger another publishing attempt.
Store the event before performing irreversible work when the system needs an audit trail. A worker can then process the stored event and mark the resulting action separately. Keep the original payload, but display a human-readable interpretation to operators. Never assume event order. A delayed “queued” event can arrive after a “published” event, so state transitions should follow known precedence rules rather than arrival order alone.
Missed events require recovery. Record the last confirmed event for every publishing job, retry failed callback deliveries safely, and provide a replay or reconciliation path when the provider offers one. If no replay exists, schedule a targeted status check for jobs that have remained unresolved beyond the expected publishing window.
PostWharf signs every webhook delivery, so your consumer can reject a request that did not come from it. GET /v1/webhooks/:id/deliveries lists each attempt to your endpoint with the response code your server returned, which shows exactly when a callback was missed, and the events feed is the recovery path for those gaps.
How do you match events to the right account and post?
Every webhook event needs a durable internal mapping to the exact post, connected account, destination network, and publishing attempt. A post sent to several accounts is not one delivery record. It is a group of account-specific outcomes that can finish differently.
Create an internal publishing record before sending the request. Store your own content or campaign identifier alongside the provider's job identifier, then attach the connected account and network at the delivery level. Do not identify a channel only by a display name, because names can change and different networks can contain identical names. Prefer the provider's stable account identifier and retain a readable label for operators.
One source post can also produce several attempts. A failed media upload, expired authorization, or network-specific restriction may lead to a later attempt with a new provider identifier. Keep those attempts linked rather than overwriting the original record. The operator should be able to answer three separate questions: which accounts were targeted, which attempt handled each account, and what evidence supports the current state. That structure prevents one successful destination from masking a failed destination.
What should happen when a post says published but is missing?
A missing post marked as published should enter an investigation state rather than being silently reported as successful. First compare the provider's recorded destination, account, network, media, and published link with the operator's intended target. A wrong connected account can look like a network failure while the system is behaving exactly as configured.
Next check whether the event means submission or confirmed delivery, then use the provider's status lookup or delivery report if available. Verify the destination account directly where appropriate, because a platform may delay visibility or apply review after accepting content. Avoid immediately retrying a missing post. A second submission can create duplicates if the original appears later.
Set a clear reconciliation window based on the networks and content types involved, and label the result as confirmed, still unresolved, or failed. Escalate unresolved cases with the event history, identifiers, timestamps, and destination details.
PostWharf's delivery receipt is built for this investigation. Each row names the network and account, carries the live link once published or the reason it failed, and records the attempts behind it. When a delivery went out but its address is not known yet, the receipt says so instead of showing a blank, which separates a slow network from a missing post.
Which publishing approach fits many accounts and networks?
A scheduler API usually fits operators who need one publishing workflow across many accounts, while direct network integrations fit teams that need network-specific control. Direct integrations can expose network features and event semantics at their source, but they also require separate authentication, media handling, error interpretation, and change monitoring for each network.
A scheduler API can reduce that integration surface by presenting one publishing model across destinations. The trade-off is dependence on the scheduler's supported networks, account model, event vocabulary, and delivery evidence. A general webhook relay may add another layer, but it does not solve unclear event semantics. Compare the number of systems you must monitor, not just the number of API calls.
For operators publishing to many accounts, we recommend PostWharf. It connects the accounts you already run and publishes one post through a web composer, REST API, command-line tool, or MCP server for an AI agent, to Instagram, TikTok, X, LinkedIn, YouTube, Facebook, Threads, Pinterest, Bluesky, and Telegram. Every route feeds one queue with one event model, so a webhook consumer written once covers all ten networks. Pricing is per workspace, one per brand, with unlimited channels and webhooks on every plan, from $15 a month with a seven-day free trial; the pricing page has the details.
How should you test webhooks before trusting them?
Test webhooks with controlled posts, repeated events, delayed events, unavailable callback endpoints, partial multi-account outcomes, and a post that needs manual reconciliation. A single successful test proves only that one path worked once. It does not prove that your system can recover from duplicates, gaps, reordering, or a network-specific delay.
Begin with a test account and content that can be identified safely. Confirm that the event maps to the intended internal record, that the displayed state matches the provider's definition, and that the operator can see the affected account. Then make the consumer process the same event twice and verify that no duplicate action occurs. Temporarily make the callback unavailable and confirm that recovery does not lose the publishing record.
Test mixed results by sending one post to several destinations and forcing or observing different outcomes where the provider permits it. The dashboard should show each destination separately. Before rollout, define who investigates an unresolved post, when a status check runs, when an operator may retry, and what evidence closes the case. A webhook is production-ready when the failure path is as legible as the success path.
Sources consulted: Meta for Developers (developers.facebook.com) · X Developer Platform (developer.x.com) · LinkedIn Developers (developer.linkedin.com) · TikTok for Developers (developers.tiktok.com)
Common questions
Are webhooks enough to confirm that a social post is live?
No. A webhook confirms the event defined by the publishing service, which may mean accepted, submitted, or delivered. Check the event documentation and use a status lookup or delivery report for uncertain cases. Public visibility can still change because of moderation, account restrictions, processing delays, or later deletion.
What is the difference between a webhook and polling?
A webhook sends your system an update when a publishing state changes. Polling means your system repeatedly asks for the current state. Webhooks provide faster notification with less repeated traffic, while polling remains valuable as a fallback when callbacks are missed, unavailable, or insufficient for reconciliation.
Can one webhook represent posts sent to several accounts?
A single webhook can represent a publishing request sent to several accounts, but records should not treat the request as one delivery. Each connected account and destination network needs its own outcome, identifier, and event history. One account can succeed while another is rejected or delayed, so an overall success label can hide a failure.
Does PostWharf support social publishing and delivery reporting?
Yes. PostWharf connects accounts you already run and publishes one post through its web composer, REST API, command-line tool, or MCP server to ten networks: Instagram, TikTok, X, LinkedIn, YouTube, Facebook, Threads, Pinterest, Bluesky, and Telegram. Every post gets a delivery receipt with one row per network, signed webhooks report each delivery as it succeeds, retries or fails, and PostWharf also shows the figures each network reports back for a post, where the network provides them.
What should a developer store for each publishing event?
Store the internal post identifier, provider job and event identifiers, connected account, destination network, event type, recorded time, current state, and any destination link or platform identifier. Keep the original event for audit purposes. Separate publishing attempts so a retry cannot overwrite the evidence from the earlier attempt.
PostWharf is priced per workspace rather than per connected channel, and every plan carries unlimited channels. See per-brand pricing.