Gestione dei Webhook: Creazione, Test e Autenticazione

I webhook consentono ad AgencyHandy di inviare dati ai tuoi sistemi esterni nel momento in cui avviene un cambiamento — senza necessità di polling. Quando si verifica un evento configurato (ad esempio, un ordine viene aggiornato o un ticket viene creato), AgencyHandy invia una richiesta HTTP POST con un payload JSON all’URL dell’endpoint specificato. Questo semplifica la sincronizzazione in tempo reale di strumenti esterni come CRM, sistemi di fatturazione o dashboard personalizzate con il tuo workspace AgencyHandy.

I workspace con piano Business Pro supportano fino a 30.000 eventi webhook per periodo di fatturazione. Verifica i limiti del tuo piano prima di configurare automazioni ad alto volume.

Eventi supportati

Puoi sottoscrivere un webhook a qualsiasi combinazione dei seguenti eventi:

Categoria	Eventi
Servizio	Creato, Aggiornato, Eliminato
Ordine	Creato, Aggiornato, Eliminato
Attività	Creata, Assegnata, Completata, Aggiornata
Fattura	Stato modificato
Cliente / Utente	Nuovo cliente aggiunto, Cliente/utente eliminato
Proposta	Inviata, Ricevuta, Accettata, Rifiutata
Ticket	Creato, Assegnato, Stato modificato
Pagamento	Ricevuto, Non riuscito
Pacchetto di Servizi	Creato, Aggiornato, Eliminato

Crea un webhook

Vai a Gestione Webhook

Nella barra laterale sinistra, vai su Integrazioni → Gestione Webhook.

Autentica il tuo token

Clicca sul pulsante Gestione per autenticare il tuo token webhook. Questo token viene utilizzato per firmare i payload in uscita in modo che tu possa verificare che provengano da AgencyHandy.

Crea un nuovo webhook

Clicca su Crea Nuovo Webhook per aprire il modulo di configurazione del webhook.

Inserisci l'URL dell'endpoint

Nel campo URL Endpoint, inserisci l’URL del sistema esterno che deve ricevere i dati del webhook. Deve essere un endpoint POST accessibile pubblicamente.

Seleziona il tipo di contenuto

Scegli JSON come tipo di contenuto. AgencyHandy invia tutti i payload webhook come application/json.

Seleziona gli eventi webhook

Scegli ogni evento che deve attivare questo webhook. Puoi selezionare eventi da più categorie — ad esempio, Ordine: Creato e Fattura: Stato modificato possono puntare entrambi allo stesso endpoint.

Attiva il webhook

Attiva il pulsante radio Attivo. Quando attivo, AgencyHandy consegna i payload per tutti gli eventi selezionati al tuo endpoint in tempo reale.

Salva la configurazione

Verifica le tue impostazioni, quindi clicca su Salva. Il webhook appare nell’elenco e inizia a consegnare eventi immediatamente.

Testa un webhook

Dopo aver creato un webhook, invia un payload di test per confermare che il tuo endpoint sia raggiungibile e stia elaborando correttamente i dati.

Apri il webhook

Dall’elenco di Gestione Webhook, clicca sul webhook che vuoi testare.

Clicca su Evento di Test

Clicca sul pulsante Evento di Test nella pagina di dettaglio del webhook.

Seleziona un evento di test

Scegli un evento di esempio dall’elenco degli eventi configurati su questo webhook (es. Ordine: Creato).

Invia il payload di test

Clicca su Invia. AgencyHandy pubblica un payload di esempio al tuo URL endpoint.

Verifica il risultato

Controlla il tuo sistema esterno per confermare che il payload di test sia arrivato e sia stato elaborato come previsto. Tornando in AgencyHandy, clicca nel webhook per esaminare la sua cronologia — puoi vedere la richiesta completa, la risposta restituita dal tuo endpoint e riconsegnare qualsiasi evento passato se necessario.

Usa uno strumento come Webhook.site o RequestBin come endpoint temporaneo durante la configurazione per ispezionare l’esatta struttura del payload prima di collegare il tuo sistema reale.

Autentica i payload dei webhook

Ogni richiesta webhook in uscita da AgencyHandy include un header di firma che il tuo endpoint può utilizzare per verificare che il payload sia autentico e non sia stato manomesso.

Header di firma

x-ah-sig: <signature>

AgencyHandy aggiunge questo header a ogni richiesta webhook. Estrai il valore dalle richieste in entrata e passalo all’endpoint di verifica.

Verifica una firma webhook

Invia la seguente richiesta per confermare che un payload sia autentico:

POST https://api.agencyhandy.com/api/v1/webhooks/verify-signature
Content-Type: application/json

string

obbligatorio

L’ID del webhook che ha ricevuto l’evento. Trovalo nella pagina di dettaglio del webhook in AgencyHandy.

string

obbligatorio

Il valore dell’header x-ah-sig dalla richiesta webhook in entrata.

string

obbligatorio

Il segreto webhook mostrato nella pagina di dettaglio del webhook in AgencyHandy.

object

obbligatorio

Il corpo JSON grezzo ricevuto dalla richiesta webhook di AgencyHandy.

const url = 'https://api.agencyhandy.com/api/v1/webhooks/verify-signature';

const postData = {
  webhookId: 'your_webhook_id',
  signature: 'your_signature',   // value of x-ah-sig header
  secret: 'your_webhook_secret',
  payload: {},                   // the parsed JSON body from AgencyHandy
};

const response = await fetch(url, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(postData),
});

const data = await response.json();
console.log(data); // { "verification_status": "SUCCESS" }

curl -X POST https://api.agencyhandy.com/api/v1/webhooks/verify-signature \
  -H "Content-Type: application/json" \
  -d '{
    "webhookId": "your_webhook_id",
    "signature": "your_signature",
    "secret": "your_webhook_secret",
    "payload": {}
  }'

Risposte

string

SUCCESS quando la firma è valida. FAILED quando la verifica fallisce (HTTP 403).

Success (200)

{
  "verification_status": "SUCCESS"
}

Failure (403)

{
  "type": "PermissionError",
  "status": 403,
  "verification_status": "FAILED"
}

Mantieni il segreto del tuo webhook riservato. Ruotalo periodicamente e aggiorna la tua logica di verifica immediatamente dopo la rotazione. Non esporlo mai nel codice lato client o in repository pubblici.

Note importanti

L’URL del tuo endpoint deve essere un URL HTTPS POST accessibile pubblicamente.
Se il tuo endpoint è temporaneamente non disponibile, controlla il pannello cronologia del webhook in AgencyHandy — puoi riconsegnare qualsiasi evento passato direttamente da lì.
Monitora regolarmente l’attività dei webhook per rilevare consegne fallite o tentativi di accesso non autorizzato.
I webhook che falliscono ripetutamente potrebbero essere messi in pausa da AgencyHandy — esamina i log di consegna per individuare i problemi in anticipo.

Inizia

Configurazione Workspace

CRM

Servizi e Ordini

Proposte e Fatture

Team e Attività

Moduli e File

Account e Fatturazione

Pagamenti

Integrazioni

Gestione dei Webhook: Creazione, Test e Autenticazione

Eventi supportati

Crea un webhook

Testa un webhook

Autentica i payload dei webhook

Header di firma

Verifica una firma webhook

Note importanti

​Eventi supportati

​Crea un webhook

​Testa un webhook

​Autentica i payload dei webhook

​Header di firma

​Verifica una firma webhook

​Note importanti

Eventi supportati

Crea un webhook

Testa un webhook

Autentica i payload dei webhook

Header di firma

Verifica una firma webhook

Note importanti