Configurare un account eBay developer in produzione (fino al webhook…

Per usare le API eBay in produzione non basta scrivere codice: serve un account developer configurato correttamente e, soprattutto, un endpoint di Marketplace Account Deletion funzionante. È un requisito obbligatorio: senza un endpoint validato, eBay non abilita il keyset di produzione. Questa guida copre l'intero percorso, dalla registrazione fino al webhook che gestisce le richieste di cancellazione dell'account.

Creare l'account developer

Il punto di partenza è developer.ebay.com:

1. registra un account developer e accetta i termini del programma API;
2. collega (o crea) l'account eBay che farà da venditore/titolare dell'app;
3. accedi alla sezione Application Keys dove gestirai i keyset.

Keyset: Sandbox vs Produzione

eBay fornisce due ambienti separati, ciascuno con il proprio keyset. Sviluppa e collauda in Sandbox, poi passa alla produzione.

Credenziale	A cosa serve
App ID (Client ID)	Identifica l'applicazione nelle chiamate e in OAuth
Cert ID (Client Secret)	Segreto usato per ottenere i token OAuth
Dev ID	Identifica l'account developer

I segreti vanno conservati in modo sicuro (es. un vault, non nel codice). Il keyset di produzione viene sbloccato solo dopo aver configurato e validato l'endpoint di cancellazione account, descritto più avanti.

OAuth e RuName

Le API Sell richiedono token OAuth. In sintesi:

• Application token (client credentials) per le chiamate che non agiscono per conto di un utente;
• User token (authorization code) per le operazioni sul conto di un venditore;
• il RuName (Redirect URL name) e gli scope definiscono il flusso di consenso e i permessi.

Configura il RuName nella sezione User Tokens del keyset: serve per il redirect dopo il consenso dell'utente.

Perché serve l'endpoint di cancellazione account

eBay deve garantire che, quando un utente chiude o richiede la cancellazione del proprio account, tutti i partner che ne detengono i dati li eliminino. Per questo ogni applicazione di produzione deve esporre un endpoint di Marketplace Account Deletion/Closure che eBay possa notificare. È un obbligo di compliance: senza endpoint validato, niente produzione.

Il flusso in due parti

L'endpoint deve gestire due tipi di richiesta:

1. GET di verifica (challenge): eBay invia un challenge_code per verificare che tu sia il proprietario dell'endpoint;
2. POST di notifica: eBay invia la notifica di cancellazione account, firmata, a cui devi rispondere rapidamente ed elaborare.

1) La verifica del challenge (GET)

Quando salvi l'endpoint nel portale, eBay chiama l'URL in GET con un parametro challenge_code. Devi calcolare un hash SHA-256 concatenando, in questo esatto ordine, tre valori: challengeCode + verificationToken + endpointURL. Quindi rispondi con HTTP 200, Content-Type: application/json e il corpo { "challengeResponse": "<hash>" }.

// Node.js (concetto)
const crypto = require('crypto');
const hash = crypto.createHash('sha256');
hash.update(challengeCode + verificationToken + endpointUrl);
const challengeResponse = hash.digest('hex');
// risposta: 200, application/json, { "challengeResponse": challengeResponse }

Attenzione ai dettagli che fanno fallire la validazione: l'endpointURL usato nell'hash deve essere esattamente l'URL configurato (stessa stringa, query inclusa se presente); l'ordine di concatenazione è vincolante; il Content-Type deve essere application/json.

Il verification token è una stringa scelta da te, lunga 32–80 caratteri, composta solo da lettere, numeri, trattino (-) e underscore (_). Lo inserisci nel portale e lo usi nell'hash.

2) La notifica di cancellazione (POST)

Superata la verifica, eBay invia le notifiche di cancellazione in POST. Due regole sono fondamentali:

• Rispondere subito con un codice 2xx (es. 200/204): l'elaborazione pesante va fatta in modo asincrono, non bloccando la risposta;
• Validare la firma dell'header x-ebay-signature con la chiave pubblica di eBay (Notification API, endpoint getPublicKey) prima di fidarti del payload.

Dopo la validazione, individua l'utente tramite gli identificatori nel payload e elimina i suoi dati dai tuoi sistemi, registrando l'operazione. Rendi l'elaborazione idempotente: la stessa notifica può arrivare più volte e non deve causare errori o effetti doppi. La Event Notification SDK di eBay semplifica la verifica della firma.

Deploy come AWS Lambda

Un endpoint serverless è una scelta naturale: niente server da gestire, HTTPS pronto e scalabilità automatica. Un'architettura tipica:

• API Gateway (HTTPS) come ingresso pubblico;
• AWS Lambda che gestisce sia la GET di challenge sia la POST di notifica;
• il verification token in una variabile d'ambiente o in un secret manager;
• elaborazione asincrona (es. coda) per la cancellazione effettiva dei dati.

Un'implementazione completa e pronta all'uso (C#/.NET su Azure Functions) per ricevere le notifiche di account deletion di eBay è disponibile qui: github.com/Capponi-Ivan-Org/ebay-account-deletion-webhook. Lo stesso pattern — verifica del challenge e gestione della notifica firmata — si applica in modo identico su AWS Lambda con API Gateway.

Configurare e validare nel portale eBay

1. vai su Application Keys → sezione notifiche di Marketplace account deletion/closure;
2. inserisci l'endpoint URL (HTTPS, niente IP interni o localhost);
3. inserisci il verification token (lo stesso usato nel codice);
4. indica un'email di contatto per gli alert;
5. premi Save: eBay invia subito il challenge e valida la risposta. Se l'hash è corretto, l'endpoint risulta verificato.

Errori comuni

• ordine di concatenazione errato nell'hash (deve essere challengeCode + verificationToken + endpointURL);
• endpointURL nell'hash diverso dall'URL salvato nel portale;
• risposta senza Content-Type: application/json o con status diverso da 200;
• endpoint non pubblico o non in HTTPS;
• POST non validata sulla firma, oppure risposta lenta che va in timeout;
• elaborazione non idempotente con notifiche ripetute.

Conclusione

Portare un'app eBay in produzione significa, oltre alle credenziali e a OAuth, esporre un endpoint di Marketplace Account Deletion che superi la verifica challenge e gestisca le notifiche firmate in modo affidabile. È un requisito di compliance, ma anche una buona occasione per impostare fin da subito sicurezza, idempotenza ed elaborazione asincrona. Documentazione ufficiale: eBay Marketplace Account Deletion.