DropfansDropfans
Help CenterFAQDevelopersMini AppSign upLog in
API v1 webhooks
Get started
Dropfans APIMake your first callConnect a creator to your appTesting without a sandboxApply for API access
Concepts
Authentication & API keysApps & approvalAPI categoriesRate limitsErrorsPagination & batch limitsModeration & statusesMoney & unitsActing for a creator: agencies and CRMs
Guides
Sell a drop end-to-endUpload images, audio and videoLinks & Telegram deep linksPost to the For You feedEarnings & balanceBroadcast one drop to many fansCreator sign-up from your platformBuild your own CRM dashboard
Webhooks
Webhooks & polling
Build with AI
Build with AIAgent prompt
API v1 (OAuth apps)
OAuth appsAPI v1 overviewAPI v1 resource listAPI v1 webhooks
API reference
API reference overview
▶Account
GETGet the account for this API keyGETGet the profile for a creatorNewPATCHUpdate the profile for a creatorNewGETGet the timezone for a creatorPUTUpdate the timezone for a creatorGETGet the subscription tier for a creatorNewPUTUpdate the subscription tier for a creatorNewGETGet the payout balance for a creator
▶Agencies
GETGet creators and personas for your agencyNewPOSTCreate an AI persona for your agencyNewPATCHUpdate an AI persona for your agencyNewDELDelete an AI persona for your agency (retire)NewPOSTReactivate an AI persona for your agencyNewPOSTCreate a creator invite for your agencyNewGETGet invites for your agency (cursor-paginated)NewDELDelete an invite for your agency (revoke)NewDELRemove a creator from your agencyNewGETGet revenue stats for your agencyNewGETGet daily earnings per creator for your agency (cursor-paginated)New
▶Creators you act for
GETGet creators you can act for (cursor-paginated)NewGETGet a creator you can act forNew
▶Vault
GETGet vault items for a creator (page-paginated)POSTUpload a vault item for a creatorDELDelete a vault item for a creatorPATCHUpdate a vault item’s folder for a creatorPATCHUpdate a vault item’s tags for a creatorGETGet vault folders for a creatorPOSTCreate a vault folder for a creatorDELDelete a vault folder for a creatorPOSTStart a video upload for a creator (step 1 of 3)POSTComplete a video upload for a creator (step 3 of 3)POSTCheck video status for a creator (batch)POSTCreate a media upload for a creatorNewPUTUpload a media upload part for a creatorNewPOSTComplete a media upload for a creatorNewGETGet a media upload for a creatorNew
▶Drops
POSTCreate a drop for a creatorGETGet drops for a creator (cursor-paginated)NewGETGet a drop for a creatorNewPATCHUpdate a drop for a creatorNewDELDelete (archive) a drop for a creatorNewPOSTAttach blur previews to a drop for a creatorPOSTCheck drop sales for a creator (batch)GETGet paid orders for a creator (cursor-paginated)New
▶Posts
POSTCreate a post for a creatorGETGet posts for a creator (page-paginated)GETGet a post for a creatorDELDelete a post for a creator
▶Earnings
GETGet the earnings overview for a creatorGETGet the earnings summary for a creatorNewGETGet transactions for a creator (cursor-paginated)NewGETGet paid tips for a creator (cursor-paginated)New
▶Links
GETGet links for a creatorNewPOSTCreate a link for a creatorNew
▶Telegram (advanced)
GETGet Telegram notification settings for a creatorPUTUpdate Telegram notification settings for a creatorPOSTRegister a Telegram notification chat for a creator
▶CRM integrations
POSTCreate a creator account for your appNewGETGet accounts for your app (cursor-paginated)NewGETGet an account for your appNewPOSTCreate an ID-check link for an accountNewGETGet the webhook endpoint for your appNewPUTUpdate the webhook endpoint for your appNewDELDelete the webhook endpoint for your appNewPOSTRotate the webhook signing secret for your appNewPOSTSend a test webhook event for your appNewGETGet details for your appNewGETGet dashboard stats for your appNewGETGet sales for your app (cursor-paginated)NewGETGet connected accounts for your appNew
▶Payouts
GETGet the payout summary for a creatorNewGETGet payouts for a creator (cursor-paginated)NewGETGet a payout for a creatorNewGETGet payout methods for a creatorNewPOSTCreate a Paxum payout method for a creatorNewPATCHUpdate a payout method for a creatorNewDELDelete a payout method for a creatorNewGETGet the MassPay profile for a creatorNewPOSTCreate the MassPay profile for a creatorNewGETGet MassPay wallet activation for a creatorNewPOSTCreate a payout request for a creatorNewPOSTCancel a payout request for a creatorNew
Resources
ChangelogAPI terms & acceptable use
Developers/API v1 (OAuth apps)/API v1 webhooks
API v1 (OAuth apps)

API v1 webhooks

Subscribe a creator’s account to webhook topics with its OAuth token, verify the HMAC-SHA256 signature on every delivery, and test a topic on demand.

View as MarkdownUpdated Nov 2, 2026
← Previous
API v1 resource list
Next →
API reference overview

Questions? support@dropfans.io

On this page
  • Subscribe
  • Delivery
  • Verify the signature
  • Test a topic
  • Topics

Let your fans show their appreciation.

Become a creatorSign up as a fan

Company

  • Blog
  • About
  • Help & FAQ
  • Availability
  • For Creators
  • Developers

Policy

  • Terms
  • Privacy
  • Refunds
  • DMCA
  • Complaints
  • USC 2257
  • AI Content
  • Cookies

Socials

Dropfans

© 2026 Dropfans. All rights reserved.

Dropfans is operated by KVIQVIEW AB, Reg. No. 559552-3852, Gamla Låssbyvägen 27, Gothenburg, Sweden.

Webhook subscriptions belong to one account and one app: subscribe with that account’s access token, and the topics you chose are POSTed to your URL whenever they happen on the account, for as long as your app holds a live grant with the topic’s scope.

Subscribe#

curl -X POST https://api.dropfans.io/v1/webhooks/subscriptions \
  -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \
  -d '{"url": "https://app.example.com/hooks", "events": ["creator.payment.succeeded", "creator.follow.created"]}'

Answers 201 {"id": "…", "signingSecret": "whsec_…"}. The signing secret is returned once: store it. Before the subscription is saved we send an unsigned verification request, {"type": "webhook.verification", "timestamp": "…"}, to your URL; any 2xx within 8 seconds passes (redirects are not followed). The URL must be public https.

The token needs read:self plus the scope of every topic. Up to 50 topics per subscription and 20 subscriptions per (account, app). GET /v1/webhooks/subscriptions lists them and DELETE /v1/webhooks/subscriptions/{id} removes one.

Delivery#

Each delivery is a JSON POST with the topic in the X-Compat-Topic header and the signature in the signature header, X-Compat-Signature. Envelope topics have this body:

{
  "id": "3f1c2a9e-5b7d-4c8e-9f10-2a3b4c5d6e7f",
  "type": "creator.follow.created",
  "timestamp": "2026-11-01T12:00:00.000Z",
  "data": { "object": "follow", "…": "…" }
}

data uses snake_case keys; money is integer cents. id identifies the occurrence and never changes across retries, so use it to de-duplicate; timestamp is set on each attempt. Legacy topics send their own flat camelCase body with an eventId instead of the envelope.

Answer with any 2xx quickly and do the work afterwards. Other answers and timeouts are retried with backoff, up to 8 attempts in all. Deliveries stop when the subscription is deleted, the grant is revoked, or the topic’s scope or category is no longer allowed for your app.

Verify the signature#

The signature header has the form t=<unix seconds>,v0=<hex>, where <hex> is HMAC-SHA256 with your signing secret over the string "<t>.<raw body>". Compute it over the raw request bytes (before any JSON parsing), compare in constant time, and reject timestamps more than about five minutes away from your clock.

import crypto from 'node:crypto';

function verify(rawBody, header, secret) {
  const m = /^t=(\d+),v0=([0-9a-f]{64})$/.exec(header || '');
  if (!m) return false;
  const want = crypto.createHmac('sha256', secret).update(`${m[1]}.${rawBody}`).digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(m[1])) < 300;
  return fresh && crypto.timingSafeEqual(Buffer.from(want), Buffer.from(m[2]));
}
import hashlib, hmac, re, time

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    m = re.fullmatch(r"t=(\d+),v0=([0-9a-f]{64})", header or "")
    if not m:
        return False
    want = hmac.new(secret.encode(), m[1].encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return abs(time.time() - int(m[1])) < 300 and hmac.compare_digest(want, m[2])

Test a topic#

POST /v1/webhooks/test with {"event": "<topic>"} sends a sample of that topic (ids prefixed TEST-) to your subscriptions that include it: 202 {"id": "…", "event": "…"}. It is 404 when no subscription of yours includes the topic, and 400 for legacy topics and for topics that cannot be tested yet (including chat topics while chat is not enabled for your app). 30 calls a minute.

Topics#

Topics delivered today:

TopicScopeFormat
payout.paidread:creatorenvelope
payout.failedread:creatorenvelope
follow.newread:creatorlegacy flat body
message.read (chat)read:chatlegacy flat body
message.received (chat)read:chatlegacy flat body
purchase.newread:creatorlegacy flat body
subscription.newread:creatorlegacy flat body
subscription.renewedread:creatorlegacy flat body
subscription.cancelledread:creatorlegacy flat body
subscription.expiredread:creatorlegacy flat body
tip.newread:creatorlegacy flat body
creator.payment.succeededread:creatorenvelope
creator.subscription.activatedread:creatorenvelope
creator.subscription.renewedread:creatorenvelope
creator.subscription.deactivatedread:creatorenvelope
creator.subscription.cancel_at_period_end_changedread:creatorenvelope
creator.post.likedread:postenvelope
creator.post.commentedread:postenvelope
creator.message.deleted (chat)read:chatenvelope
creator.refund.createdread:creatorenvelope
creator.dispute.createdread:creatorenvelope
creator.follow.createdread:creatorenvelope
creator.message.received (chat)read:chatenvelope
creator.message.sent (chat)read:chatenvelope
creator.message.mass_sent (chat)read:chatenvelope
creator.message.read (chat)read:chatenvelope
creator.notificationread:creatorenvelope

The subscription endpoint also accepts the other published topic names, so an app can register its full list without errors, but nothing is delivered for them yet. Chat topics are delivered once chat is enabled for your app. Ignore topics you do not handle.