Skip to main content

Webhook subscriptions

Not generally available yet

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_username returns 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
FieldTypeRequiredDescription
urlStringYesPublic https:// URL, at most 2048 characters. Private and local addresses are refused.
eventsArrayYesEvent names, at least one (see Events). social_account.connected and social_account_connected are the same.
profile_usernameStringNoOnly events of this profile. Omit it for every profile of the account.
sourceStringNoLabel of the integration that created it (a-z, 0-9, _, ., -; max 40), e.g. n8n.
nameStringNoFree 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) and active_count. Every filter is optional; status is active or disabled.
  • To check whether your subscription still exists, list with ?url=<your url>&status=active and compare the events.
  • DELETE stops sending right away and answers {"success": true, "deleted": true, "id": "whsub_..."}. Deleting it again answers 404: 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:

HeaderValue
X-Upload-Post-Signaturesha256= + HMAC-SHA256 of "{timestamp}.{raw_body}" with your account webhook_secret
X-Upload-Post-TimestampUnix seconds of this attempt
X-Upload-Post-EventEvent name
X-Upload-Post-DeliveryDelivery id, the same on every retry
X-Upload-Post-Attempt1, 2, 3...
X-Upload-Post-SubscriptionThe 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_reasonWhen
endpoint_goneThe URL answered 404 or 410 several times in a row (the workflow was deleted).
failing_too_longIt kept failing for days.
blocked_urlThe URL is not an allowed destination (it resolved to a private address).
profile_removedIts 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": "..."}.

StatusreasonMeaning
400invalid_body, invalid_url, invalid_events (+ allowed_events), invalid_profile_username, invalid_source, invalid_name, invalid_status, invalid_eventThe request is not valid.
403team_member_forbiddenTeam members cannot create subscriptions.
404not_found, account_not_found, profile_not_foundNo such subscription, account or profile.
409subscription_limit_reached (+ limit)10 active subscriptions already: delete one first.
409subscription_disabled, blocked_urlTest of a disabled subscription, or a URL that is not allowed.
503webhook_subscriptions_disabledNot available yet.

See also the error code catalog.