API reference

Update the webhook endpoint for your app

Sets the https endpoint that receives your app’s events. The first call also creates the signing secret and returns it **once** as `secret`. Store it; later calls don’t return it (use rotate-webhook-secret).

View as MarkdownUpdated Oct 17, 2026

PUT/api/external/v1/webhooksalso served at /api/external/webhooksNew

Sets the https endpoint that receives your app’s events. The first call also creates the signing secret and returns it once as secret. Store it; later calls don’t return it (use rotate-webhook-secret).

Leave events out to get every event, including ones added later.

Authentication

Send the creator's API key as a bearer token: Authorization: Bearer dpfn_…. See Authentication & API keys.

Request body

Content type: application/json

Name	Type	Required	Description
`url`	string	Required	Public https URL (no IPs, no localhost, no credentials). Format: uri
`events`	string[]	Optional	Subset of events to receive. Omit for all.

All events

{
  "url": "https://crm.example.com/hooks/dropfans"
}

Responses

200Saved.

Name	Type	Description
`url`	string	The saved endpoint. Format: uri
`events`	string[]	Events delivered.
`secret`	string	Signing secret (`whsec_…`) — only on the first save.

Example response

{
  "url": "https://crm.example.com/hooks/dropfans",
  "events": [
    "drop.paid",
    "drop.refunded",
    "account.kyc_updated"
  ],
  "secret": "whsec_8d1e…"
}

Errors

Status	Body	When
400	`{"error":"url must use https"}`	Not a public https URL, or unknown events.
401	`{"error":"Unauthorized","code":"unauthorized"}`	Missing or invalid API key.
403	`{"error":"This endpoint needs a key bound to an approved app.","code":"app_key_required"}`	A Personal key was used.
403	`{"error":"Use the app owner's key for this endpoint.","code":"owner_key_required"}`	The key was minted by a creator for themselves. App-level calls need a key held by your app owner: their own, or one their agency minted for its personas or managed creators.
400	`{"error":"This endpoint acts as the key’s own account or app — call it without /creators/{creatorId}.","code":"creator_scope_not_allowed"}`	Called under /api/external/v1/creators/{creatorId}/ — this endpoint always acts as the key’s own account, agency or app.
403	`{"error":"This app does not have the webhooks API category enabled. Contact support to enable it.","code":"api_category_disabled","category":"webhooks"}`	Your app has the App webhooks [API category](/developers/concepts/api-categories) switched off.

Rate limiting

Every response carries the X-RateLimit-Tier header and, on limited tiers, the per-minute and per-day trios — read X-RateLimit-Remaining and X-RateLimit-Reset instead of hardcoding limits. Details in Rate limits.

Code samples

curl -X PUT "https://www.dropfans.io/api/external/v1/webhooks" \
  -H "Authorization: Bearer $DROPFANS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://crm.example.com/hooks/dropfans"
}'

const res = await fetch(`https://www.dropfans.io/api/external/v1/webhooks`, {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.DROPFANS_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "url": "https://crm.example.com/hooks/dropfans"
  }),
});
console.log(await res.json());

import os
import requests

res = requests.put(
    "https://www.dropfans.io/api/external/v1/webhooks",
    headers={"Authorization": f"Bearer {os.environ['DROPFANS_API_KEY']}"},
    json={
        "url": "https://crm.example.com/hooks/dropfans",
    },
)
print(res.json())

← Previous

Get the webhook endpoint for your app

Delete the webhook endpoint for your app

Questions? support@dropfans.io