Vai al contenuto
AurionAI

API per sviluppatori: utilizzo e webhook

4 min di letturaDi Emmanuel Yazbeck

Le pagine dell'API per sviluppatori mostrano come i programmi utilizzano l'API di AurionAI e consentono di inviare gli eventi di AurionAI ai propri sistemi tramite webhook.

Disponibilità: tutti i profili. Solo gli amministratori.

Prerequisiti

  • Hai il ruolo Proprietario o Amministratore. Gli altri ruoli non possono aprire queste pagine.
  • Per i webhook: un indirizzo HTTPS sul tuo lato che accetta richieste POST con un corpo JSON.

Aprire le pagine dell'API per sviluppatori

  1. Nella barra superiore, seleziona il tuo nome o la tua immagine per aprire il menu utente.
  2. Seleziona Impostazioni del tenant.
  3. Vai alla scheda API Sviluppatori.
  4. Seleziona Dashboard utilizzo API o Gestione webhook.

La scheda API per sviluppatori nella pagina Impostazioni tenant.

Esaminare l'utilizzo dell'API

La pagina "API Usage Dashboard" mostra il traffico dell'API di AurionAI per la tua organizzazione.

  1. Sotto "Window", scegli "Last 1 day", "Last 7 days" o "Last 30 days". Il valore predefinito è sette giorni.
  2. Leggi i quattro totali: "Total Requests", "Error Rate", "Rate-Limit Hits" e "Webhook Success".
  3. Leggi "Top API Paths" per vedere quali indirizzi vengono chiamati più spesso, con i relativi errori.
  4. Leggi "Daily Trend" per vedere il traffico giornaliero.
  5. Seleziona "Refresh" per caricare i dati più recenti.

Registrare un webhook

  1. Nella pagina "Webhook Management", vai su "Create Subscription".
  2. In "Target URL", digita l'indirizzo HTTPS del tuo ricevitore.
  3. Sotto "Events", seleziona gli eventi che desideri ricevere. Gli eventi sono raggruppati: conversazioni, messaggi, contatti, ticket, chiamate, knowledge base e sistema.
  4. Seleziona "Create webhook".
  5. Una finestra di dialogo mostra il segreto di firma. Seleziona "Copy secret" e conserva il segreto in un luogo sicuro. AurionAI lo mostra solo questa volta.
  6. Seleziona "I have saved my secret".

Il nuovo webhook appare sotto "Subscriptions" con lo stato "Active".

Verificare la firma di un webhook

Ogni consegna è una richiesta POST con un corpo JSON e le seguenti intestazioni:

  • X-Webhook-Event: il nome dell'evento, ad esempio ticket.created.
  • X-Webhook-Timestamp: l'ora della consegna.
  • X-Webhook-Signature: la firma della consegna.

Per verificare che una consegna provenga da AurionAI:

  1. Prendi il valore di X-Webhook-Timestamp, un punto e il corpo grezzo della richiesta, in quest'ordine.
  2. Calcola un HMAC-SHA256 di questo testo con il tuo segreto di firma.
  3. Scrivi il risultato in esadecimale e confrontalo con X-Webhook-Signature. Accetta la consegna solo quando sono uguali.

Testare, mettere in pausa o eliminare un webhook

  • Seleziona "Send test" per inviare una consegna di prova. Un webhook in pausa non può ricevere un test.
  • Seleziona "Pause" per interrompere temporaneamente le consegne e "Resume" per riprenderle.
  • Seleziona "Delete" e conferma per rimuovere il webhook.
  • La pagina elenca le ultime consegne, con il loro stato, il numero di tentativi e lo stato HTTP del tuo ricevitore.

Risultato

AurionAI invia ogni evento selezionato al tuo indirizzo. Una consegna viene considerata riuscita quando il tuo ricevitore risponde con uno stato 2xx. In caso contrario, AurionAI riprova più tardi, fino a un massimo di cinque tentativi in totale.

Se qualcosa va storto

  • "Webhook URL is required." Digita l'indirizzo del tuo ricevitore.
  • "Select at least one event to subscribe to." Seleziona almeno un evento.
  • Un messaggio indica che l'URL del webhook deve iniziare con https. AurionAI invia webhook solo a indirizzi HTTPS.
  • Un messaggio indica che l'indirizzo è bloccato o non può essere risolto. AurionAI rifiuta gli indirizzi privati, locali e sconosciuti. Usa un indirizzo pubblico che si risolva nel DNS.
  • La firma non corrisponde. Usa il corpo grezzo così come ricevuto, prima di qualsiasi analisi. Usa il segreto di questo webhook. Se hai perso il segreto, elimina il webhook e ricrealo.
  • Le consegne falliscono. Controlla lo stato HTTP nell'elenco delle consegne. Il tuo ricevitore deve rispondere con uno stato 2xx.
  • "No webhooks configured" sotto "Webhook Success". La tua organizzazione non ha ancora nessun webhook per sviluppatori.

Articoli correlati

Hai ancora bisogno di aiuto? Invia una richiesta o .