Webhooks (coming soon) & polling today
Outbound webhooks for third-party apps are planned; until then, these polling patterns cover sales, video processing and moderation.
Outbound webhooks for third-party apps are planned but not shipped. Everything in the first half of this page is a preview of the intended contract and is subject to change — build against the polling patterns below for now, and watch the changelog.
Planned events#
| Event | Fires when |
|---|---|
drop.paid | a buyer completes checkout on a drop |
tip.received | a tip lands |
subscription.started | a fan subscribes |
subscription.canceled | a subscription ends |
vault.item.moderated | a vault item leaves PENDING |
post.moderated | a post leaves PENDING |
Planned envelope — a JSON POST to your endpoint:
{ "id": "evt_…", "type": "drop.paid", "timestamp": "2026-08-19T12:00:00Z", "data": { … } }Deliveries would carry an HMAC signature header for verification. Again: names, shapes and semantics may all change before launch.
Today: the three polling patterns#
Until webhooks ship, three loops cover the same ground. Budget them against your rate tier — the day windows are 5,000 requests (personal) and 50,000 per key (app).
1. Sales — check-status#
Poll POST /drops/check-status with the product ids you are waiting on — up to 200 per call, chunked. Check on demand (the buyer says "paid") plus a periodic sweep every 1–5 minutes. The maths: one sweep a minute is 1,440 requests/day per 200-drop chunk — fine on the app tier, a quarter of a personal day budget, so personal keys should sweep every 5 minutes instead.
2. Video processing — video-status#
While a video is processing after upload, poll POST /vault/video-status (up to 50 ids) every 10–15 seconds until isReady or isFailed. Processing is minutes, not hours — stop polling on any terminal state.
3. Moderation — posts and vault#
- Posts: GET /posts?status=PENDING or GET /posts/{id} every 30–60 seconds while something is pending.
- Vault items: GET /vault?includePending=true every few minutes after a batch upload, until nothing is PENDING.
Back off when nothing is pending — a moderation poll with an empty pending set is a wasted request. All three loops together, run sensibly, fit inside the app tier with room to spare.
Next: Rate limits or Sell a drop end-to-end.
Questions? [email protected]