Testare i webhook

1. Invia un evento di prova

Dalla dashboard (Impostazioni → Sviluppatori → Webhook → Invia evento di prova) o tramite l'API:

curl -X POST https://api.nembol.com/rest/v1/webhook_endpoints/{id}/test \
  -H "Authorization: Bearer $NEMBOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "order.created" }'

La risposta ti dice subito se il tuo endpoint ha risposto e con quale stato:

{ "delivered": true, "response_status": 200 }

Gli eventi di prova sono consegne reali, con lo stesso formato e la stessa firma (quindi anche il tuo codice di verifica viene messo alla prova). data.object è un esempio con la forma reale del tipo che hai richiesto (un ordine, un'inserzione, un prodotto…), costruito con record fittizi (TEST-SKU-1, ordine TEST-1001, id che non esistono da nessuna parte), e data.test è true. Il tuo handler viene eseguito end to end esattamente come per un evento reale: controlla data.test prima di scrivere qualsiasi cosa nel tuo sistema. Un type sconosciuto risponde 422.

2. Sviluppo in locale

La tua macchina di sviluppo non è raggiungibile da internet. Le opzioni:

• Punta un endpoint webhook verso un servizio di cattura (es. webhook.site) per ispezionare payload e header. Va bene per guardare, ma non può verificare le firme al posto tuo.
• Crea un tunnel verso localhost con ngrok http 3000 (o cloudflared) e registra l'URL del tunnel come endpoint in modalità test. Questo è il ciclo end to end completo: verifica della firma, il tuo handler, il tuo 2xx.

3. Chiavi in modalità test e webhook

Gli endpoint webhook creati con una chiave nbl_test_ ricevono solo eventi sintetici (invii di prova e operazioni simulate), mai traffico di produzione. Gli endpoint live ricevono solo eventi reali. Tieni separati i due nella tua configurazione.

4. Checklist prima del lancio

• Verifica della firma attiva (e fallisce se alteri anche un solo byte).
• L'handler risponde 2xx in < 10s; il lavoro pesante avviene in modo asincrono.
• Un event.id duplicato non ha effetto (le consegne sono at-least-once).
• I valori di type sconosciuti ricevono conferma, non un errore.
• Un job di riconciliazione scansiona GET /events per recuperare ciò che manca.

Ultimo aggiornamento il 20 ottobre 2026