Patreon developer docs · 2026-06-10

Patreon webhooks: events, setup, and use cases for developers (2026)

Patreon webhooks fire in real time when patron membership events occur — new pledges, tier changes, cancellations, and payment failures. This covers the event types, payload structure, setup steps in the Creator Portal, and the most common use cases: Discord role automation, CRM sync, and membership gate triggers.

Webhook events Patreon supports

Patreon fires webhooks for six event types, all prefixed with the resource type:

The most frequently used events for membership automation are members:pledge:create (new paying patron — trigger onboarding), members:pledge:delete (patron cancels — revoke access), and members:update (payment declined — patron_status changes to declined_patron).

members:create fires for all members including free-tier followers, which is a larger set than just paid patrons. If your webhook handler should respond only to paid pledges, filter on patron_status === "active_patron" in the payload rather than relying on the event type alone.

How to set up a Patreon webhook

Webhook setup requires a Patreon API client:

1. Go to portal.patreon.com/create/clients-and-api-keys and create a new client application. Give it a name (internal — patrons do not see this), set a redirect URI (required for OAuth flow setup; can be a placeholder if you are only using webhooks), and save.
2. On the client application page, find the Webhooks section. Add a new webhook: enter your endpoint URL (a public HTTPS URL — Patreon cannot post to localhost), select the events you want to subscribe to, and save.
3. Copy the webhook secret Patreon generates. You use this to verify that incoming requests are genuinely from Patreon and have not been tampered with.
4. Deploy your webhook endpoint. Patreon expects an HTTP 200 response within 10 seconds. If your handler takes longer than 10 seconds (e.g., external API calls), return 200 immediately and process the event asynchronously via a queue.

Webhook payload structure

Patreon webhooks use JSON:API formatting. The top-level envelope:

{
  "data": {
    "type": "member",
    "id": "...",
    "attributes": { ... },
    "relationships": { ... }
  },
  "included": [ ... ],
  "meta": {
    "event_type": "members:pledge:create"
  }
}

Key attributes in the member object:

The included array contains related objects: the patron's user record (with full_name and email if your OAuth scope includes identity[email]), the tier the patron is entitled to, and the campaign. The tier relationship is important: a patron upgrading from $5 to $15 generates a members:pledge:update event where the newly entitled tier's ID changes in the relationships — not just the amount in attributes.

Verifying webhook signatures

Every webhook request from Patreon includes an X-Patreon-Signature header: the HMAC-SHA256 hex digest of the raw request body, keyed with your webhook secret.

Verification in Node.js:

const crypto = require('crypto');

function verifyPatreonSignature(rawBody, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(signature, 'hex')
  );
}

Use the raw request body (before JSON parsing) for the HMAC computation. Parsing and re-stringifying the JSON may change whitespace and invalidate the signature.

Common use cases

Discord role automation: While Patreon's native Discord integration handles role assignment without code, custom webhook handlers are used when you need more control: assigning different Discord roles based on pledge amount rather than just tier (e.g., $25+ patrons get a "Founder" role in addition to the standard $25 tier role), logging new patron events to a private mod channel, or sending a personalized welcome DM to new patrons via a Discord bot.

CRM and email platform sync: On members:pledge:create, add the patron's email to your email list (Kit, Beehiiv, Mailchimp) via their API, tagged as "patron" or with their tier name. On members:pledge:delete, remove the patron tag or move them to a "former patron" segment. This keeps your CRM in sync with Patreon patron status without manual exports. The patron's email is only available in the webhook payload if your OAuth scope includes identity[email].

Membership-gated web app: If you run a web app or tool that patrons access as a membership benefit, webhooks handle the access lifecycle: grant access on members:pledge:create, check tier on members:pledge:update (did they downgrade below the required tier?), and revoke on members:pledge:delete or when patron_status becomes declined_patron.

Patron analytics: Log every webhook event to a database or data warehouse (Postgres, BigQuery). Over time you accumulate a patron event stream: join date, tier changes, churn date. This gives you the cohort retention data that Patreon's native analytics does not provide — how long patrons at each tier stay subscribed, and at what tier amounts churn spikes.

Handling failures and retries

If your endpoint does not return HTTP 200 within 10 seconds, Patreon marks the delivery as failed and retries. Patreon's retry policy is exponential backoff over approximately 24 hours. After repeated failures, Patreon may disable the webhook and notify you via email.

Best practices for reliability:

• Return 200 immediately before doing any async work (use a job queue)
• Log every incoming webhook payload before processing, so you can replay events if your handler fails
• Treat webhooks as eventually consistent: Patreon may send duplicate events for the same action; make your handler idempotent (processing the same event twice should not double-create records)
• Expose a health check URL so you can verify your webhook endpoint is reachable before debugging event delivery

November 2026 Apple billing and webhooks

After November 1, 2026, iOS-billed subscriptions route through Apple. The webhook events themselves do not change — members:pledge:create fires for new iOS patrons just as it does for web-billed patrons. The change shows up in the will_pay_amount_cents attribute: for an iOS patron on a $10 tier, this will reflect the $10 pledge amount, but the creator's net payout for that patron is lower due to Apple's cut (collected by Apple, not visible in the Patreon payload).

If you are building a revenue projection tool or creator dashboard that uses webhook data, do not use currently_entitled_amount_cents as the creator's revenue — it represents the patron's pledge, not the creator's net. Add iOS billing detection logic (not directly available in the webhook payload — you would need to cross-reference with the Patreon API's billing method field) to accurately project net payout.

FAQ