Webhooks & Notifications

Upload-Post allows you to receive real-time notifications about upload statuses and social account connection changes. This eliminates the need to poll endpoints for status updates.

Configuration

You can configure notifications in the Upload-Post Dashboard:

Configure Notifications

You can choose to receive notifications via:

Webhook: A POST request sent to your server with a JSON payload.
Telegram: A message sent to a configured Telegram chat.

Configuration via API

You can also configure your notification preferences programmatically using the API.

Endpoint: POST https://app.upload-post.com/api/uploadposts/users/notifications

Authentication: Requires a valid API Key.

Request Body:

{
  "channels": {
    "webhook": true,
    "telegram": false
  },
  "webhook_url": "https://your-server.com/webhook-endpoint",
  "telegram_chat_id": "123456789",
  "webhook_events": {
    "upload_completed": true,
    "social_account_connected": true,
    "social_account_disconnected": true,
    "social_account_reauth_required": true
  }
}

Response:

{
  "success": true,
  "notifications": {
    "channels": { "webhook": true, ... },
    "webhook_url": "...",
    "webhook_events": { "upload_completed": true, "social_account_connected": true, ... },
    ...
  }
}

Webhook Events

You can subscribe to specific event types using the webhook_events object. Set each event key to true to receive it, or false to disable it. If omitted, all events are enabled by default.

Event	Description
`upload_completed`	Fired when an upload process completes (success or failure).
`social_account_connected`	Fired when a social account is connected or reconnected.
`social_account_disconnected`	Fired when a social account is disconnected (manually or automatically).
`social_account_reauth_required`	Fired when a social account requires re-authentication.

Webhook Payloads

`upload_completed`

Sent when an upload process completes (whether successfully or with a failure).

{
  "event": "upload_completed",
  "job_id": "a1b2c3d4e5f6...",
  "user_email": "[email protected]",
  "profile_username": "your_profile_username",
  "platform": "instagram",
  "media_type": "video",
  "title": "My Awesome Video",
  "caption": "Check this out! #cool",
  "result": {
    "success": true,
    "url": "https://www.instagram.com/p/C1234567890/",
    "publish_id": "17987654321098765",
    "post_id": "17987654321098765",
    "error": null
  },
  "created_at": "2024-03-15T14:30:00.000000"
}

Field Descriptions

Field	Type	Description
`event`	`string`	The type of event: `upload_completed`.
`job_id`	`string`	The persistent job identifier returned when the post was created or scheduled. Use this to correlate webhook events with your original API requests. Only present when the upload was triggered via the API with a `job_id`.
`user_email`	`string`	The email address of the user who initiated the upload.
`profile_username`	`string`	The username of the profile associated with the upload.
`platform`	`string`	The social platform where the post was uploaded (e.g., `instagram`, `youtube`, `tiktok`).
`media_type`	`string`	The type of media uploaded (`video`, `photo`, or `text`).
`title`	`string`	The title provided for the post.
`caption`	`string`	The caption or description of the post.
`result`	`object`	An object containing the outcome of the upload attempt.
`result.success`	`boolean`	`true` if the upload was successful, `false` otherwise.
`result.url`	`string`	The direct URL to the published post (if available and successful).
`result.publish_id`	`string`	The ID assigned to the post by the platform.
`result.error`	`string`	A description of the error if the upload failed.
`created_at`	`string`	The timestamp of the event in ISO 8601 format.

`social_account_connected`

Sent when a social account is successfully connected or reconnected via OAuth.

{
  "event": "social_account_connected",
  "user_email": "[email protected]",
  "platform": "instagram",
  "account_name": "my_instagram_handle",
  "status": "connected",
  "profile_username": "your_profile_username",
  "created_at": "2024-03-15T14:30:00.000000"
}

`social_account_disconnected`

Sent when a social account is disconnected. This can happen due to:

Manual disconnection by the user
Automatic disconnection due to persistent authentication failures (account blocked)

{
  "event": "social_account_disconnected",
  "user_email": "[email protected]",
  "platform": "tiktok",
  "account_name": "my_tiktok_handle",
  "status": "disconnected",
  "profile_username": "your_profile_username",
  "reason": "manual_disconnect",
  "created_at": "2024-03-15T14:30:00.000000"
}

`social_account_reauth_required`

Sent when a social account's access token can no longer be refreshed and the user must re-authenticate. This typically happens when:

The refresh token has expired
The user revoked access on the platform
Multiple consecutive token refresh attempts have failed

{
  "event": "social_account_reauth_required",
  "user_email": "[email protected]",
  "platform": "youtube",
  "account_name": "UCxxxxxxxxx",
  "status": "reauth_required",
  "reason": "token_refresh_threshold_exceeded",
  "created_at": "2024-03-15T14:30:00.000000"
}

Connection Status Event Fields

Field	Type	Description
`event`	`string`	The event type: `social_account_connected`, `social_account_disconnected`, or `social_account_reauth_required`.
`user_email`	`string`	The email address of the account owner.
`platform`	`string`	The social platform (e.g., `instagram`, `youtube`, `tiktok`, `x`, `linkedin`, `facebook`, `threads`, `pinterest`, `reddit`, `bluesky`, `snapchat`, `google_business`, `tiktok_business`).
`account_name`	`string`	The account identifier on the platform (e.g., username, channel ID).
`status`	`string`	The new connection status: `connected`, `disconnected`, or `reauth_required`.
`profile_username`	`string`	The Upload-Post profile associated with this account (if applicable).
`reason`	`string`	Additional context for the status change (e.g., `manual_disconnect`, `account_blocked`, `token_refresh_threshold_exceeded`, `max_auth_strikes`). Only present for `disconnected` and `reauth_required` events.
`created_at`	`string`	The timestamp of the event in ISO 8601 format.

Usage Notes

Idempotency: While we strive to deliver each notification exactly once, you should handle potential duplicate events based on your own unique identifiers if necessary (though post_id or publish_id can serve this purpose for successful posts).
Security: Ensure your webhook endpoint is secure (HTTPS) and verify the data as needed for your application logic.
Event Filtering: Use the webhook_events field in your notification settings to subscribe only to the events you need. If not specified, all events are enabled by default.
Replacing Polling: If you were previously polling the profile endpoint to check connection status, subscribe to social_account_connected, social_account_disconnected, and social_account_reauth_required events instead.

Configuration​

Configuration via API​

Webhook Events​

Webhook Payloads​

upload_completed​

Field Descriptions​

social_account_connected​

social_account_disconnected​

social_account_reauth_required​

Connection Status Event Fields​

Usage Notes​