API, webhook e SSO del feedback

L’API di integrazione riceve ticket e feedback tramite chiavi di progetto; i webhook notificano gli eventi con una firma da verificare. Il proprietario configura chiavi e destinazioni. Il SSO identifica i visitatori della bacheca di feedback tramite il tuo backend, senza esporre segreti al browser.

Creare ticket o feedback e ricevere webhook firmati

Il proprietario crea un’integrazione con Nuova integrazione sulla riga del titolo di Impostazioni del progetto → Integrazioni. Un’integrazione issues invia lavoro al triage; un’integrazione feedback raccoglie esigenze con voti e stato pubblico. La chiave mdy_ viene mostrata una sola volta. Conservala solo sul server in MINDDY_API_KEY o MINDDY_FEEDBACK_KEY, mai nel browser, in Git o nei log. Ogni integrazione è elencata con nome, prefisso della chiave, data di creazione, ultimo utilizzo e un badge Ticket o Feedback. Per revocarne una, il proprietario sceglie Revoca nel suo menu ⋯ e conferma; l’integrazione porta allora il badge Revocata e passa in fondo all’elenco, attenuata. La revoca è permanente; una chiave sconosciuta o revocata restituisce 401 invalid_api_key. Ogni chiave appartiene a un progetto e a un tipo: usarla sull’endpoint sbagliato restituisce 403 wrong_key_kind. Un’integrazione non è una persona: non ha un ruolo nel progetto e mantiene i permessi fissi del suo tipo quando cambiano i ruoli dei membri. I lettori non vedono le integrazioni.

Inviare i campi corretti

GET /api/v1/issues/options restituisce categorie, priorità ed effort disponibili. POST /api/v1/issues richiede un titolo non vuoto e accetta descrizione Markdown, priorità, effort e categorie opzionali.

Il ticket entra sempre nel triage; dall’esterno non puoi scegliere stato, assegnatario o parent. La risposta 201 contiene id, number, identifier e status. Per i campi del feedback, l’identità dell’autore e la moderazione, segui la procedura di raccolta dei feedback.

curl --fail-with-body --request POST "$MINDDY_ORIGIN/api/v1/issues" \
  --header "Authorization: Bearer $MINDDY_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"title":"Segnalazione di esempio","description":"Riprodurre con dati dimostrativi","priority":"low","effort":"s"}'

Verificare e deduplicare eventi

Le integrazioni issues possono inviare issue.created, issue.status_changed e issue.updated. Una nuova destinazione webhook deve essere scelta dal proprietario con Configura il webhook… nel menu ⋯ dell’integrazione. Una volta impostata la destinazione, la riga Webhook sotto l’integrazione mostra l’ultima consegna, accettata o rifiutata con la data, oppure Nessuna consegna ancora. Gli agenti possono regolare eventi e ambito di una destinazione esistente o disattivarla; non possono aprire un nuovo canale di uscita. L’ambito integration include solo i ticket creati con quella chiave; all include l’intero progetto.

X-minddy-Signature contiene il prefisso sha256= e un HMAC-SHA256 calcolato sui byte originali. La chiave HMAC è il digest SHA-256 della chiave API, rappresentato come stringa esadecimale minuscola. Confronta la firma in tempo costante prima di fidarti del payload, senza analizzarlo e riserializzarlo. X-minddy-Delivery corrisponde a delivery_id: usa questo UUID per eliminare i duplicati.

Gestire errori e limiti

La consegna è best effort: il timeout è di cinque secondi, seguito da un solo nuovo tentativo immediato per errori di rete o risposte 5xx. Dopo il secondo fallimento l’evento viene scartato. Sono possibili duplicati e consegne fuori ordine. Salva il payload verificato, rispondi subito con 2xx e poi elaboralo. issue.updated raggruppa le modifiche; per description e plan riporta solo il nome del campo. Controlla quindi lo stato corrente. Per 429 rispetta Retry-After; gli errori di validazione restituiscono 422 e la quota definitiva restituisce 403 issue_limit_reached. Un timeout di creazione non prova un fallimento: verifica prima di riprovare. La votazione dei feedback ha un endpoint e limiti propri.

Collegare la raccolta di feedback e il SSO

Il proprietario crea una chiave di integrazione feedback nelle impostazioni del progetto. Conserva la chiave, mostrata una sola volta, come MINDDY_FEEDBACK_KEY nella configurazione segreta del backend. Non inserirla mai nel codice del browser. Imposta MINDDY_ORIGIN sull’origine dell’istanza di destinazione, senza barra finale.

curl -i "$MINDDY_ORIGIN/api/v1/feedback"   -H "Authorization: Bearer $MINDDY_FEEDBACK_KEY"   -H 'Content-Type: application/json'   --data '{"title":"Mostrare data di consegna","body":"Il supporto ha bisogno della data prevista.","user":{"external_id":"demo-user-1","name":"Lettore demo"}}'

Fornisci un titolo non vuoto di massimo 200 caratteri, un corpo facoltativo di massimo 10.000 e user.external_id e/o user.email. L’ID esterno ammette 255 caratteri, l’email 254 e il nome 200. Il backend garantisce l’identità; l’acquisizione anonima viene rifiutata. Il successo restituisce HTTP 201 con id, status, review_state, voti e pseudonimo. La bacheca non deve essere attiva per ricevere feedback. user.name è facoltativo. analyze è un booleano, true per impostazione predefinita; la stringa "false" viene rifiutata. false salta moderazione, categorizzazione e unione per quel feedback, pubblica il testo invariato e imposta lo stato di revisione published senza attesa. Controlla review_state e valida l’identità dell’autore sul server. Questo stato non attiva la bacheca e non supera le regole di visibilità o lo stato di spam. L’API crea feedback pubblici per impostazione predefinita e non accetta un parametro di visibilità privata.

Voti, errori e webhook

Invia {"user":{"external_id":"demo-user-1"}} tramite POST a /api/v1/feedback/<id>/vote con gli stessi header. Ogni identità dispone di un voto; ripeterlo è idempotente. Un feedback unito restituisce 409 post_merged con la destinazione canonica.

La creazione consente 20 chiamate al minuto per chiave; i voti, 60. Rispetta Retry-After in caso di 429. Controlla 401 invalid_api_key, 403 wrong_key_kind, 400 invalid_json e gli errori di campo 422 prima di riprovare. La creazione non è un aggiornamento idempotente: se perdi la risposta, controlla la casella feedback del team prima di ripetere. Le chiavi feedback non offrono webhook di issue in uscita. Un’integrazione issue configurata separatamente supporta quel canale con firma propria e consegna senza garanzia.

Identificare i visitatori tramite SSO

Come proprietario, attiva la bacheca e configura il suo segreto SSO distinto. Il backend firma un JWT HS256 con sub stabile, exp obbligatorio ed email e nome facoltativi. Usa al massimo 600 secondi di validità e un jti univoco; la verifica tollera 60 secondi di scarto dell’orologio. Reindirizza subito a /f/<board-token>?sso=<jwt>. Ogni token viene consumato una sola volta per bacheca; un nuovo tentativo richiede un token appena firmato. Non riutilizzare la chiave di acquisizione come segreto SSO. Mantieni i token fuori da log e schermate condivise.

Verifica che il visitatore apra Il mio feedback con l’identità prevista. Un token scaduto richiede un nuovo reindirizzamento. Se il segreto è compromesso, rinnovalo tramite la conferma della bacheca e aggiorna contemporaneamente il backend. Il codice email resta l’alternativa quando il SSO non è disponibile.

Scegliere un obiettivo per un feedback

Per un’integrazione feedback, il proprietario può scegliere l’obiettivo alla creazione, oppure più tardi nella riga Obiettivo dei nuovi feedback sotto l’integrazione esistente in Impostazioni del progetto → Integrazioni; quel selettore può anche creare un nuovo obiettivo. Sono accettati solo obiettivi attivi dello stesso progetto. Ogni nuovo invio POST /api/v1/feedback eredita l’impostazione, anche con analyze: false; non inviare objective_id nel payload API. La risposta 201 include l’objective_id assegnato o null. Cambiare o rimuovere l’impostazione riguarda solo gli invii futuri. Un obiettivo non disponibile restituisce 422 objective_not_found: scegline uno attivo o rimuovi l’impostazione prima di riprovare. La revisione di Numo non deduce obiettivi. La conversione eredita l’obiettivo e le categorie del feedback.