ZenStudio — Developer receiver guide
Build one small receiver on an existing destination website. ZenStudio sends a JSON post over HTTPS; the destination saves a real public post and its own media copy, then returns success.
Connection contract
- Add the destination in ZenStudio under Connected Sites and copy its private Connection token.
- Store that token in the destination host's encrypted server settings as
ZENSTUDIO_TOKEN. Never put it in browser code, public settings, logs, or rendered pages. - Expose one public
POSTreceiver at its final HTTPS address, enter that address in ZenStudio, then use Test receiver.
POST https://your-site.example/api/zenstudio/receive
Content-Type: application/json
x-zenstudio-event: video.published
x-zenstudio-token: <private token copied from ZenStudio>Compare the received token to ZENSTUDIO_TOKEN in constant time. Reject missing or incorrect tokens with HTTP 401. Accept only HTTPS, JSON, a request body limit suitable for the site, and these events: ping, video.published, video.updated, article.published, and article.updated. Return 200 with {"ok":true} only after a ping has been accepted.
Save a real, independent post
- Upsert by
data.idso repeated deliveries update the same post instead of creating duplicates. - For video payloads with
source_type: "file", downloadstream_urlandthumbnail_urlserver-side into the destination's own media storage before returning success. Store the destination-owned URLs on the post. - For direct-link and embed videos, preserve the provided video, embed, thumbnail, and source-credit fields. Those remain available only while the original provider keeps them online.
- Render a native player from the destination-owned file or
stream_url, otherwise a safe iframe fromembed_url. Do not insert untrustedplayer_html. - Return a 2xx JSON response only after the post and required media are committed:
{"ok":true,"stored":true,"post_id":"<same data.id>"}. ZenStudio verifies the acknowledgement matches the sent content ID; plain 2xx responses are logged as unconfirmed failures. Return non-2xx if anything fails so ZenStudio can show it and retry.
ZenStudio does not send deletion events. Deleting, unpublishing, or shutting down ZenStudio must never remove an already-published destination post.
Example payload
{
"event": "video.published",
"sent_at": "2026-11-16T12:00:00.000Z",
"data": {
"id": "video-uuid",
"title": "Destination title",
"description": "Video description",
"category": "News",
"tags": ["updates"],
"source_type": "file",
"stream_url": "https://getzenstudio.lovable.app/api/public/v1/media/video-uuid",
"embed_url": null,
"thumbnail_url": "https://getzenstudio.lovable.app/api/public/v1/media/video-uuid?kind=thumbnail",
"origin_url": null,
"attribution_required": false,
"duration_seconds": 124,
"published_at": "2026-11-16T12:00:00.000Z",
"updated_at": "2026-11-16T12:00:00.000Z"
}
}Launch checklist
- A request with no token or the wrong token returns 401 and changes nothing.
- The ZenStudio receiver test returns JSON
{"ok":true}. - Publishing returns JSON
{"ok":true,"stored":true,"post_id":"<same data.id>"}only after the destination post is saved. - Publish one uploaded video. Confirm the destination post plays from destination storage.
- Publish the same item again. Confirm it updates instead of duplicating.
- Delete or unpublish the item in ZenStudio. Confirm the destination post remains live.