Patreon spegne API v1: endpoint e webhook da migrare

Secondo il changelog di Patreon, dal 7 ottobre 2026 gli endpoint della Public API v1 smettono di rispondere e i webhook legacy pledges cessano di inviare eventi per chi non aveva richiesto una proroga entro quella data. L’accesso esteso dura fino al 20 gennaio 2027, termine finale indicato per tutti. La scadenza riguarda le integrazioni che leggono iscrizioni, campagne o post tramite i vecchi percorsi e quelle che ricevono ancora eventi sui contributi.

Per ripristinare quelle funzioni occorre spostare le chiamate agli endpoint v2, creare un client OAuth v2 con gli scope necessari e sostituire i trigger pledges con eventi basati sulla risorsa member. La registrazione del nuovo client, da sola, non modifica le richieste già presenti nel codice né il formato dei webhook che l’applicazione sa leggere.

Da identity ai post: i percorsi da sostituire

Il passaggio dalle richieste pledge di Patreon alla risorsa member dell’API v2.

Gli endpoint v2 usano il prefisso /api/oauth2/v2/ al posto di /api/oauth2/api/, ma il cambio comprende anche il modello dei dati. La risorsa pledge lascia il posto a member, che rappresenta il rapporto fra sostenitore e creator. Queste sono le corrispondenze per le chiamate principali:

Identità: /api/oauth2/api/current_user → /api/oauth2/v2/identity.
Campagne dell’utente: /api/oauth2/api/current_user/campaigns → /api/oauth2/v2/campaigns.
Membri di una campagna: /api/oauth2/api/campaigns/{campaign_id}/pledges → /api/oauth2/v2/campaigns/{campaign_id}/members.
Singolo post: /api/oauth2/api/posts/{post_id} → /api/oauth2/v2/posts/{post_id}.

Il passaggio da pledge a member richiede di rivedere le condizioni usate per concedere accesso ai contenuti. Fra gli attributi del membro figurano patron_status, last_charge_status e currently_entitled_amount_cents: descrivono stato dell’iscrizione, ultimo addebito e importo che dà attualmente diritto ai benefici. Un parser costruito sui campi del vecchio pledge non può trattare la nuova risposta come se avesse struttura e significato identici.

In v2 gli attributi vanno richiesti esplicitamente con fields e le risorse collegate con include: per impostazione predefinita restano soltanto tipo e identificativo della risorsa. Le parentesi quadre nei nomi dei parametri, per esempio fields[member], devono essere codificate nell’URL. Anche un endpoint raggiungibile può quindi restituire meno dati di quelli attesi se la richiesta omette i campi che l’integrazione usa per nome, stato o diritto d’accesso. Per scorrere gli elenchi dei membri, la paginazione v2 usa inoltre page[count] e page[cursor], con il cursore successivo nella risposta.

Un client OAuth v2 richiede scope diversi

Gli scope granulari di v2 richiedono un nuovo client OAuth. identity dà accesso ai dati di base dell’utente autenticato; identity[email] serve per la sua email e identity.memberships per le sue iscrizioni. Per leggere i membri di una campagna occorre campaigns.members, mentre campaigns.members[email] e campaigns.members.address autorizzano rispettivamente email e indirizzo, quando quest’ultimo è stato raccolto. Campagne e post richiedono campaigns e campaigns.posts.

La corrispondenza con i vecchi permessi chiarisce dove intervenire: users diventa identity, con identity[email] se l’applicazione usa l’email; pledges-to-me diventa identity.memberships; my-campaign passa a campaigns. Il precedente scope pledges copriva dati che in v2 ricadono nei permessi per membri, email e indirizzi. Conviene quindi richiedere gli scope necessari alle funzioni effettivamente usate, senza presumere che il nome di un vecchio permesso basti a individuare il sostituto.

Va controllato anche il percorso chiamato dopo l’autorizzazione: un token ottenuto con un client v2 può ancora essere usato dal codice per inviare richieste a un endpoint v1 ormai ritirato. Il controllo interessa sia il login dei sostenitori sia le operazioni successive, come la sincronizzazione periodica dei membri e il recupero dei post. Inoltre l’identificativo di un member è distinto da quello dell’utente: una ricerca del singolo membro deve usare il member ID.

I trigger pledges e il nuovo payload dei webhook

I webhook pledges legacy di Patreon si fermano mentre gli eventi members della versione v2 proseguono.

I nomi dei trigger dismessi sono pledges:create, pledges:update e pledges:delete. Per gli eventi relativi al contributo, i corrispondenti trigger v2 sono:

pledges:create → members:pledge:create;
pledges:update → members:pledge:update;
pledges:delete → members:pledge:delete.

Esistono anche members:create, members:update e members:delete, ma riguardano il ciclo di vita della membership e non equivalgono in ogni caso a un cambiamento del contributo. Per esempio, members:pledge:create non scatta quando una persona diventa membro gratuito o riscatta un regalo. members:delete si applica alla cancellazione di una membership senza pagamenti precedenti; negli altri casi la fine del contributo può presentarsi come aggiornamento dello stato del membro. La scelta del trigger incide quindi sulle regole che assegnano o revocano l’accesso.

Il ricevitore deve adattarsi anche al payload v2. L’intestazione X-Patreon-Event identifica l’evento e X-Patreon-Signature contiene il digest esadecimale HMAC-MD5 calcolato sul corpo del messaggio con il secret del webhook; la verifica va fatta sul corpo ricevuto prima di elaborare l’evento. I dati inviati dipendono dagli scope del webhook: senza campaigns.members manca il dato del membro e senza campaigns.members[email] manca la sua email. Dal 7 ottobre il portale webhook mostra gli scope associati a ciascun webhook, rendendo visibile questo vincolo nella configurazione.

La scadenza è già visibile nelle integrazioni

Brad Guigar ha registrato il ritiro dell’API v1 nel suo resoconto dell’8 ottobre sul plugin Patreon per WordPress. Nello stesso testo descrive la rimozione temporanea del plugin dalla directory WordPress.org, avvenuta il giorno precedente al ritiro dell’API, senza attribuire un nesso causale fra i due eventi.

Un caso più diretto riguarda Sideloadly: dopo un’autorizzazione Patreon riuscita, un utente ha ricevuto l’errore «Pledge fetch failed — obsolete token?». Il team dell’app, rispondendo alla segnalazione, ha attribuito il problema alla disattivazione delle API v1 e ha scritto: «Patreon issue should be fixed now on our server». Il caso mostra come l’autorizzazione OAuth possa completarsi anche quando la successiva richiesta di dati sui contributi fallisce.

Per le integrazioni coperte da proroga, il 20 gennaio 2027 resta la data entro cui completare il passaggio. Dopo quel termine non è previsto accesso agli endpoint v1 o consegna degli eventi pledges legacy.