⏱ 10 min di lettura

Webhook avanzati

Come usare il sistema webhook di NexusPass per vendere qualsiasi cosa: oggetti di gioco, licenze software, accessi a servizi esterni e abbonamenti per altri bot Discord.

ℹ️

I webhook avanzati richiedono un endpoint HTTP sul tuo server o servizio. Se non hai un backend, puoi usare servizi come Vercel, Cloudflare Workers o Railway per crearne uno velocemente.

Come funziona il sistema webhook

Quando un utente completa un pagamento, invece di assegnare solo un ruolo Discord, NexusPass può chiamare un URL che tu controlli con i dettagli del pagamento.

Il flusso è:

Utente paga nel server Discord
Stripe notifica NexusPass
NexusPass chiama il tuo endpoint con i dati del pagamento
Il tuo endpoint fa quello che vuoi (assegna oggetti, attiva licenze, ecc.)

Configura un prodotto con reward type Webhook

Durante il setup del prodotto su NexusPass, nel campo Tipo premio seleziona Webhook.

Compila i campi:

URL: l'endpoint del tuo servizio
Secret: una chiave segreta per verificare che la chiamata venga da NexusPass

💡

Puoi avere sia un ruolo Discord che un webhook — NexusPass li esegue entrambi dopo il pagamento.

Cosa riceve il tuo endpoint

NexusPass invia una richiesta POST al tuo URL con questo body JSON:

json

{
  "discord_user_id":  "123456789012345678",
  "discord_guild_id": "987654321098765432",
  "product_name":     "Spada Leggendaria",
  "price_amount":     999,
  "currency":         "eur",
  "payment_type":     "one_time"
}

E questi header:

http

POST /api/grant-item HTTP/1.1
Content-Type: application/json
X-Webhook-Secret: la-tua-chiave-segreta

⚠️

Verifica sempre il campo X-Webhook-Secret prima di processare la richiesta, altrimenti chiunque potrebbe chiamare il tuo endpoint.

Esempio: assegna oggetti in un gioco (Node.js)

Node.js / Express

app.post('/api/grant-item', async (req, res) => {
  // 1. Verifica il secret
  const secret = req.headers['x-webhook-secret']
  if (secret !== process.env.NEXUSPASS_WEBHOOK_SECRET) {
    return res.status(401).json({ error: 'Unauthorized' })
  }

  const { discord_user_id, product_name } = req.body

  // 2. Fai quello che vuoi con i dati
  await database.grantItem({
    userId:   discord_user_id,
    item:     product_name,
    quantity: 1,
  })

  // 3. Rispondi con 200 per confermare la ricezione
  res.status(200).json({ success: true })
})

💡

Adatta questo esempio al tuo linguaggio e framework preferito. La logica è la stessa.

Esempio: attiva una licenza software (Python)

Python / FastAPI

@app.post("/api/activate-license")
async def activate_license(
    request: Request,
    payload: dict
):
    # 1. Verifica il secret
    secret = request.headers.get("x-webhook-secret")
    if secret != os.environ["NEXUSPASS_WEBHOOK_SECRET"]:
        raise HTTPException(status_code=401)
    
    discord_user_id = payload["discord_user_id"]
    
    # 2. Genera una licenza univoca
    license_key = generate_license_key()
    
    # 3. Salvala nel DB
    await db.save_license(
        user_id=discord_user_id,
        key=license_key
    )
    
    # 4. Manda la chiave via DM Discord (opzionale)
    await send_discord_dm(
        user_id=discord_user_id,
        message=f"La tua licenza: {license_key}"
    )
    
    return {"success": True}

Gestione errori e retry

Il tuo endpoint deve:

Rispondere con HTTP 200 entro 10 secondi
Implementare l'idempotenza usando discord_user_id come chiave
Loggare gli errori per debug

Esempio di risposta di errore che NexusPass gestisce correttamente:

json

// Risposta in caso di errore (NexusPass loggerà l'errore)
{
  "success": false,
  "error": "Utente non trovato nel database di gioco"
}

💡

NexusPass non fa retry automatici in caso di errore — se il tuo endpoint restituisce un errore, l'oggetto non viene assegnato. Assicurati che il tuo servizio sia affidabile.

Casi d'uso comuni

🎮Oggetti di gioco

🔑Chiavi di gioco

📦Accessi software

🤖Abbonamenti bot

💎NFT / Asset digitali

🎓Corsi online

← Configura Stripe Risolvi problemi →