How to get webhook alerts when a social post fails

Choose how you want to receive failure alerts

Want a push alert the instant TimeToPost gives up on a post? Webhooks are the straightforward choice. Head to Settings → Webhooks, add an HTTPS endpoint, pick the event you care about, and TimeToPost fires off a signed JSON POST to your server. For failure alerts the event is post.failed.

If push delivery is not your thing and you would rather have a system or agent poll status on demand, the MCP server is the other supported option. It runs with your account permissions, can read posts and scheduler health, and works well for workflow checks instead of immediate inbound alerts. The hosted server is described here: TimeToPost MCP.

Set up a TimeToPost webhook endpoint for post failure events

In the dashboard, create a webhook endpoint under Settings → Webhooks and point it at your own HTTPS receiver. Then select post.failed so TimeToPost only sends the failure event you actually want.

The docs also say the endpoint can be created through the API with POST /api/webhooks, and the response includes a signing secret shown once. Create or rotate that secret only when you are ready to store it securely. No sticky notes on the monitor, please, unless your threat model is a raccoon.

Verify the alert is truly about a failed post

Do not trust the payload just because it looks polite.

Before your receiver acts on the webhook, validate the raw request body, confirm the TimeToPost-Signature header with HMAC-SHA256, reject timestamps older than 5 minutes, and deduplicate using TimeToPost-Event-Id. TimeToPost documents the signature format as t=<timestamp>,v1=<hex hmac-sha256>, and it says verification must use the exact raw bytes that arrived, not re-serialized JSON.

If you want the full security walkthrough, see How to verify TimeToPost webhook signatures before trusting a delivery. That is the step that keeps a random POST body from masquerading as a real alert.

Build the receiver so it handles retries and late arrivals

Your endpoint should answer with a 2xx within 10 seconds. Anything slower, or anything non-2xx, counts as a failure. TimeToPost retries failed deliveries, and the same event can arrive more than once, so your handler needs to be idempotent.

That means two practical rules:

1. Deduplicate by TimeToPost-Event-Id.
2. When the alert lands late or out of order, fetch the current post state by id from the API before you decide what to notify.

That second step matters because ordering is not guaranteed, and a retry can show up after the post has already moved again. Delivery history is available in the dashboard, which is handy when you are trying to figure out whether your server flaked out or the internet did its usual thing.

Worked example: alert on post.failed and open the post record

Say your webhook receiver gets this event:

{
  "id": "evt_3f9c1b7a5d2e48c0a1b2c3d4e5f60718",
  "type": "post.failed",
  "created": "2026-10-24T18:30:02.114Z",
  "data": {
    "postId": "post_123",
    "status": "failed",
    "partial": false
  }
}

Your receiver would do three things:

1. Verify the signature against the raw body.
2. Check that evt_3f9c1b7a5d2e48c0a1b2c3d4e5f60718 has not already been processed.
3. Look up post_123 with the API, using GET /api/posts/:id, so the notification can show the current post record instead of guessing from the webhook alone.

A simple alert payload might then say something like, “Post failed, current status is failed, open the post record for details.” That is better than a vague alarm bell that just screams into the void.

TimeToPost’s scheduling docs note that FAILED means no account could be published to, and the per-account error is stored with the post result. So the API record is where you would pull the failure context from after the webhook tells you which post needs attention.

If you only need to inspect failures in your own workflow

If your workflow is agent-driven and you do not need a push alert, the MCP server can read posts and scheduler health under your account permissions. That makes it a reasonable fit for polling-style checks, internal tooling, or an assistant that periodically reviews status.

For the hosted server and its tools, see TimeToPost MCP. For actual failure alerts, though, webhook delivery is still the direct route. Push beats rummaging around later, which is charmingly inefficient otherwise.