Webhook subscriptions
Webhook subscriptions are not generally available yet. Until they are, every route on this page answers 503 Service Unavailable with "reason": "webhook_subscriptions_disabled". The account webhook is not affected and keeps working as today.
The account webhook is one URL per account (plus one per profile). A subscription is an extra destination with its own list of events and, optionally, one profile. Integrations create one when they start listening and delete it when they stop: that is what the n8n trigger node does, and the same pattern as Zapier/Make "REST hooks".
- Up to 10 active subscriptions per account.
- Creating is idempotent: the same
url+events+profile_usernamereturns the existing subscription (and reactivates it if it was disabled). - Each subscription is independent from the account webhook: you can have both, and an event goes to every destination that asked for it.
- Team members (
X-Act-As-User) cannot create subscriptions: they would keep receiving the owner's events after leaving the team.
Create a subscription
POST /api/uploadposts/webhooks/subscriptions
| Field | Type | Required | Description |
|---|---|---|---|
url | String | Yes | Public https:// URL, at most 2048 characters. Private and local addresses are refused. |
events | Array | Yes | Event names, at least one (see Events). social_account.connected and social_account_connected are the same. |
profile_username | String | No | Only events of this profile. Omit it for every profile of the account. |
source | String | No | Label of the integration that created it (a-z, 0-9, _, ., -; max 40), e.g. n8n. |
name | String | No | Free label (max 100). |
curl -X POST https://api.upload-post.com/api/uploadposts/webhooks/subscriptions \
-H "Authorization: Apikey YOUR_API_KEY" -H "Content-Type: application/json" \
-d '{"url": "https://example.app.n8n.cloud/webhook/0b1f", "events": ["upload_completed"], "source": "n8n", "name": "My workflow"}'
201 Created for a new one, 200 OK ("created": false) when it already existed; reactivated: true when it was disabled and is active again. Sending name or source again updates them.
{
"success": true,
"created": true,
"reactivated": false,
"subscription": {
"id": "whsub_65f0c2a9e1b4d7c3a8f9e012",
"url": "https://example.app.n8n.cloud/webhook/0b1f",
"events": ["upload_completed"],
"profile_username": null,
"source": "n8n",
"name": "My workflow",
"status": "active",
"disabled_reason": null,
"disabled_at": null,
"created_at": "2026-11-16T20:31:02Z",
"updated_at": "2026-11-16T20:31:02Z",
"last_delivery_at": null,
"health": {"consecutive_failures": 0, "last_failure": null, "last_failure_at": null, "paused_until": null}
}
}
List, read and delete
GET /api/uploadposts/webhooks/subscriptions?status=active&source=n8n&url=<exact url>
GET /api/uploadposts/webhooks/subscriptions/{id}
DELETE /api/uploadposts/webhooks/subscriptions/{id}
- The list returns
subscriptions(newest first, active and disabled),limit(10) andactive_count. Every filter is optional;statusisactiveordisabled. - To check whether your subscription still exists, list with
?url=<your url>&status=activeand compare theevents. DELETEstops sending right away and answers{"success": true, "deleted": true, "id": "whsub_..."}. Deleting it again answers404: an integration can treat that as "already deleted".
Send a test event
POST /api/uploadposts/webhooks/subscriptions/{id}/test
Body (optional): {"event": "<one of the subscription's events>"}; by default its first event. Upload-Post sends one signed sample at once, with the same keys as the real event plus "test": true (for the post approval events, the real event's approval object with made-up values). It is logged as a test delivery, never retried, and never counts towards disabling the subscription. The answer says whether your endpoint answered 2xx:
{"success": true, "ok": true, "delivery": {"delivery_id": "...", "status": "delivered", "test": true, "target": "subscription", "...": "..."}}
What your endpoint receives
The body is the same as the account webhook for that event (payloads). The headers are the same too, plus the subscription id:
| Header | Value |
|---|---|
X-Upload-Post-Signature | sha256= + HMAC-SHA256 of "{timestamp}.{raw_body}" with your account webhook_secret |
X-Upload-Post-Timestamp | Unix seconds of this attempt |
X-Upload-Post-Event | Event name |
X-Upload-Post-Delivery | Delivery id, the same on every retry |
X-Upload-Post-Attempt | 1, 2, 3... |
X-Upload-Post-Subscription | The subscription id (whsub_...) |
The secret is the account's: GET /api/uploadposts/users/notifications → notifications.webhook_secret (created with your first subscription if you had none). Rotating it (POST /users/webhook-secret) changes it for subscriptions too.
Deliveries go out from a queue: the first one can take up to about a minute. Failed deliveries follow the same retry schedule as the account webhook and are listed in the delivery log with GET /api/uploadposts/webhooks/deliveries?subscription_id=whsub_... (they show "target": "subscription"); you can redeliver them as usual.
When Upload-Post stops sending
A subscription disables itself (status: disabled) and says why in disabled_reason:
disabled_reason | When |
|---|---|
endpoint_gone | The URL answered 404 or 410 several times in a row (the workflow was deleted). |
failing_too_long | It kept failing for days. |
blocked_url | The URL is not an allowed destination (it resolved to a private address). |
profile_removed | Its profile was deleted. |
A disabled subscription stays listed for 30 days. Create it again (same url, events, profile_username) to reactivate it.
Events
upload_completed, social_account_connected, social_account_disconnected, social_account_reauth_required, dm_received, comment_received, telegram_update, review_received, review_updated, customer_media_received, listing_google_update, listing_duplicate, listing_control_changed and post_analytics_updated. While those features are on, also youtube_video_published / youtube_video_updated (YouTube push) and the post approval events. An unknown name answers 400 with reason: invalid_events and the allowed_events list.
Errors
Errors have the shape {"success": false, "reason": "...", "message": "..."}.
| Status | reason | Meaning |
|---|---|---|
| 400 | invalid_body, invalid_url, invalid_events (+ allowed_events), invalid_profile_username, invalid_source, invalid_name, invalid_status, invalid_event | The request is not valid. |
| 403 | team_member_forbidden | Team members cannot create subscriptions. |
| 404 | not_found, account_not_found, profile_not_found | No such subscription, account or profile. |
| 409 | subscription_limit_reached (+ limit) | 10 active subscriptions already: delete one first. |
| 409 | subscription_disabled, blocked_url | Test of a disabled subscription, or a URL that is not allowed. |
| 503 | webhook_subscriptions_disabled | Not available yet. |
See also the error code catalog.