Creazione dei Webhook

Le schermate in questo articolo sono in lingua inglese. L'interfaccia di Zoho CRM potrebbe variare in base alla versione e alla lingua impostata.

I Webhook facilitano la comunicazione con applicazioni di terze parti inviando notifiche web istantanee ogni volta che si verifica un evento in Zoho CRM. Con i Webhook, è possibile configurare URL HTTP e associarli nelle regole del flusso di lavoro per automatizzare l'intero processo di notifica. Per informazioni generali sui Webhook, consultare webhooks.org.

Scenari

Dopo la chiusura di una trattativa in Zoho CRM, è possibile inviare le informazioni del cliente al software di contabilità (ad es. Zoho Books) e generare automaticamente una fattura per il cliente.
È possibile aggiungere iscritti alla mailing list nel software di Email Marketing (ad es. MailChimp) in base ai lead o contatti raccolti dal proprio sito web utilizzando i moduli web di Zoho CRM.
È possibile attivare promemoria SMS ai commerciali sul campo riguardo incontri con i clienti, dimostrazioni e altri eventi.
È possibile generare un preventivo nel software di contabilità (ad es. Zoho Books) non appena la fase dell'opportunità viene modificata da Prospecting a Price Quote.
Dopo la chiusura di una trattativa in Zoho CRM, è possibile calcolare automaticamente la commissione per i commerciali nell'applicazione Sales Commission costruita su Zoho Creator.

Destinatari

Utenti CRM con permessi di gestione del flusso di lavoro
Programmatori con competenze nelle REST API

Disponibilità

Permesso richiesto

Gli utenti con il permesso di gestione del flusso di lavoro nel proprio profilo possono accedere a questa funzionalità.

Elenco dei campi nel Webhook

Nome campo	Descrizione	Limiti e tipo di dati
Nome	Specificare il nome del webhook.	Alfanumerico (100)
Descrizione	Aggiungere una descrizione per il webhook.	200 caratteri
Metodo	Selezionare il tipo di metodo API - POST, GET, PUT e DELETE . POST consente di inserire i valori nei campi dell'applicazione associata. GET consente di recuperare informazioni per aggiornare i campi di un record in Zoho CRM PUT aggiorna il valore esistente nell'applicazione associata. DELETE elimina il valore esistente nell'applicazione associata. Nota: Per impostazione predefinita, il sistema selezionerà il metodo POST.	Picklist
URL da notificare	Specificare l'URL dell'API REST dell'applicazione di terze parti. È possibile utilizzare facoltativamente campi di unione come ${Accounts.Account Name}. Suggerimento: se non si è sicuri del campo di unione, andare alla sezione Body, scegliere "Raw" dal menu a discesa Type per abilitare l'area di testo, quindi digitare # per inserire un campo di unione. È possibile copiarlo nel campo URL to Notify. È inoltre possibile copiare i campi di unione utilizzati altrove nel CRM. I campi di unione devono seguire questo formato: ${Module.Field}.	300 caratteri
Tipo di autorizzazione	Selezionare il tipo di autorizzazione desiderato - General (include API Key o AUTH Token) e Connection (OAuth, API Key, ecc.)	Radio Button
Connection	Se Connection è selezionato, è possibile scegliere la connessione appropriata dall'elenco. Nota: l'opzione Connection elencherà solo le connessioni attive esistenti. Scegliere una connessione esistente o crearne una nuova. Ulteriori informazioni sulle connessioni . Se viene aggiunta una nuova connessione, fare clic sull'icona di aggiornamento vicino al campo Choose connection, per visualizzare la connessione appena aggiunta nel menu a discesa.	Radio Button
Modulo	Scegliere uno dei moduli di Zoho CRM. Moduli supportati: Moduli primari del CRM, come lead, account, contatti, trattative, ecc. Riunioni e Attività Nota: Non è possibile configurare webhook per i moduli Registro chiamate e Note.	Picklist
Header	Nota: Parametri URL - Un URL contiene informazioni sul trigger tra Zoho CRM e altre applicazioni. Le informazioni di trigger in un URL webhook sono tipicamente classificate come Header e Body. I parametri aggiunti alla sezione header conterranno dati che si sincronizzeranno con l'header dell'altra applicazione. Oltre alle informazioni di trigger, l'header può contenere abitualmente API Key/Auth token. Per formare i parametri URL dell'Header, scegliere Module Parameters e/o custom parameters.	Limite Header: Un webhook può contenere fino a 10 parametri URL Header.
Module Parameters	Specificare il nome del parametro, il tipo di parametro e il valore del parametro corrispondente. Aggiungere più parametri per costruire la stringa. Questo formato è dinamico e il CRM offre le opzioni per scegliere i valori dei campi dalla picklist. Il tipo di parametro include Moduli primari del CRM Utenti Organizzazione	-
Custom Parameters	Specificare il nome del parametro CRM e il valore corrispondente per il webhook. Il nome e il valore sono come configurati. Poiché il valore nel parametro personalizzato è statico, questa coppia chiave/valore viene utilizzata principalmente per inviare Auth token, token di sicurezza, API key, ecc.
Body	La parte Body dell'URL contiene informazioni nella stringa URL sul trigger verso l'altra applicazione. È possibile scegliere di utilizzare Form-Data o Raw dalla picklist, per configurare la parte body dell'URL. Form-Data: Consente di costruire la parte body dell'URL semplicemente concatenando il nome del parametro e il tipo di parametro o il valore del parametro. È possibile costruire Form-Data in 3 modi - Module Parameters, Custom Parameters e User-Defined Parameters. User defined parameter: Specificare il nome del parametro e il valore del parametro. Questo formato è anch'esso dinamico, con la possibilità di scegliere il tipo di valore dall'opzione di inserimento del campo di unione utilizzando # Raw Data: Oltre alla formazione dei parametri, è possibile anche scrivere i propri valori di dati nell'editor di testo selezionando l'opzione Raw Data come tipo di body. È possibile inserire dati in uno dei seguenti formati XML, JSON, HTML o TEXT.È inoltre possibile utilizzare la funzione del campo di unione # per indicare un valore di campo all'interno dello script.	Limite Raw Data : Un webhook può contenere fino a 15000 caratteri nell'editor di testo raw data.
Anteprima URL	L'anteprima URL visualizza l'URL completo del webhook per i metodi di richiesta GET e DELETE, mentre per i metodi POST e PUT, viene visualizzato solo l'URL configurato. Per visualizzare l'anteprima dell'URL, fare clic sull'icona Aggiorna nella parte inferiore dell'editor di testo. È inoltre possibile copiare l'URL.	Sola lettura

Note:

Se il metodo di richiesta è selezionato come POST o PUT, vengono visualizzati i tipi di configurazione - Header e Body.
Se il metodo di richiesta è selezionato come DELETE, vengono visualizzati l'header e il Form-Data della configurazione body.
Se il metodo di richiesta è selezionato come GET, viene visualizzato solo il body del tipo di configurazione in formato form-data.
Non è possibile utilizzare i dati personali dei partecipanti come email, telefono, numero di cellulare, ecc. come parametro nel Webhook nel modulo Riunioni.

Configurazione dei Webhook

La configurazione dei Webhook include i seguenti tre passaggi:

Creare un webhook.
Associare il webhook a una regola del flusso di lavoro.
Testare l'integrazione del webhook.

Per creare un webhook

Andare su Setup > Automation > Actions > Webhooks.
Nella pagina Webhooks , fare clic su Configure Webhook.
Nella pagina New Webhook , specificare tutti i parametri necessari.
Fare clic su Save.

Riconoscere i valori dei campi di unione non supportati

A volte si potrebbe notare che i valori dei campi di unione utilizzati nell'editor Value Description del webhook vengono ora visualizzati come ${Unsupported_Field}. Di seguito sono riportati alcuni dei motivi per cui ciò accade.

Campo personalizzato eliminato

Il campo di unione il cui valore è stato inserito è stato eliminato. Se l'editor Value Description del webhook contiene ancora il valore del campo di unione di un campo eliminato, quel valore verrà visualizzato come ${Unsupported_Field}.

Campo di ricerca personalizzato eliminato

Il campo di ricerca personalizzato il cui valore è stato inserito è stato eliminato. Se l'editor Value Description del webhook contiene ancora il valore del campo di unione di un campo di ricerca eliminato, quel valore verrà visualizzato come ${Unsupported_Field}.

Campo non presente nell'elenco dei campi di unione disponibili

Se è stato utilizzato il valore del campo di unione di un campo che non è tra l'elenco dei campi di unione disponibili per il modulo selezionato, verrà visualizzato come ${Unsupported_Field}.

Ad esempio, se si inserisce il valore del campo di unione ${Leads.Lead Id} nell'editor Value Description per il modulo Trattative, verrà visualizzato come campo non supportato.

Integrazioni/Funzionalità disabilitate

Quando una funzionalità o un'integrazione è stata disabilitata per il proprio account, anche i campi creati come parte dell'integrazione non saranno più disponibili per l'account dopo la disattivazione. Se un valore del campo di unione di tale campo è stato inserito nell'editor Value Description , verrà visualizzato come ${Unsupported_Field}. Questo è applicabile alle seguenti funzionalità/integrazioni.

Integrazione Google Ads - I campi di Google Ads non più disponibili non saranno supportati.
Visitor Tracking (Integrazione Zoho SalesIQ): I campi di Visitor Tracking non più disponibili non saranno supportati.
Territory Management - I campi non più disponibili non saranno supportati.
Multivaluta - Le valute disattivate non saranno supportate.

Per associare il webhook a una regola del flusso di lavoro

Andare su Setup > Automation > Workflow Rules
Nella pagina Workflow Rules , fare clic su Create Rule.
Nella pagina Create New Rule , specificare i parametri della regola del flusso di lavoro.
Sotto Workflow Actions, selezionare webhooks.
Nel popup Call Webhook, selezionare il webhook richiesto e fare clic su Associate.
Fare clic su Save.

Per testare l'integrazione del webhook

Aggiungere dati di test nel CRM in base ai criteri della regola del flusso di lavoro.
Nella propria applicazione verificare i dati ricevuti da Zoho CRM tramite notifica webhook.
Se si verifica un errore o una discrepanza nei dati, modificare le impostazioni del webhook in Zoho CRM.
Continuare questo test fino a ottenere i dati richiesti da Zoho CRM nella propria applicazione.

Note:

È possibile associare fino a 6 (1 azione istantanea e 5 azioni basate sul tempo) webhook per regola del flusso di lavoro.

Limite di trasferimento dati:

Header: Un webhook può contenere fino a 10 parametri URL Header (inclusi parametri modulo e personalizzati).
Body:
- Form-data: 25 parametri modulo, 10 parametri personalizzati e un parametro strutturato con lunghezza fino a 10000 caratteri.
- Raw data type: È possibile trasmettere fino a 15000 caratteri. Se si utilizzano parametri di tipo Raw data, non è possibile utilizzare il tipo Form-data.

Non è possibile recuperare dati da altre applicazioni verso Zoho CRM utilizzando i webhook.
È necessario aggiornare regolarmente il ticket API in base ai limiti delle applicazioni di terze parti.
Non si riceverà alcuna notifica email se l'integrazione Webhook ha smesso di funzionare a causa di un problema nell'API di terze parti.
In caso di errore nel processo, il Webhook invierà prima una notifica, il sistema Zoho CRM invierà una seconda notifica dopo 15 minuti. Successivamente, il sistema non invierà più notifiche Webhook per quel particolare trigger del flusso di lavoro.
Se si supera il conteggio massimo giornaliero, il sistema non invierà le rimanenti notifiche Webhook alle applicazioni di terze parti e notificherà l'errore all'amministratore.
Nel campo URL to Notify , se si desidera specificare un numero di porta, si prega di notare che sono supportati solo i numeri di porta 80 o 443.
Zoho CRM offre l'opzione di selezionare il formato Date/Date Time richiesto e il Time Zone durante la configurazione dei parametri del Webhook.
Limiti per i Webhook:

Edizione Professional - 50.000 chiamate/giorno o 100 chiamate/utente/giorno (il valore inferiore).
Edizione Enterprise - 500.000 chiamate/giorno o 500 chiamate/utente/giorno (il valore inferiore).
Edizione Ultimate - 1.000.000 chiamate/giorno o 1000 chiamate/utente/giorno (il valore inferiore).

Scenario aziendale 1

Calcolare la commissione di vendita nell'app Zoho Creator alla chiusura di un'opportunità in Zoho CRM.

Scopo

I responsabili vendite e il team paghe possono utilizzare l'app Sales Commission per calcolare la retribuzione dei commerciali secondo una formula predefinita impostata dalla propria organizzazione (ad esempio, il 2% fisso del contratto chiuso o dell'importo di vendita). Questa applicazione aiuta a ridurre le inserzioni manuali, minimizzare gli errori e risparmiare tempo nel calcolo delle commissioni per i commerciali. Inoltre, i commerciali possono monitorare le proprie commissioni mensili in un'unica posizione centralizzata.

Prerequisiti

Account nell'applicazione Zoho Creator
Permesso di accesso alle API di Zoho
Familiarità con Zoho Creator

Procedura

Creare l'app Sales Commission in Zoho Creator (consultare il tutorial di Zoho Creator sulla creazione di app)
Configurare il webhook in Zoho CRM
Configurare la regola del flusso di lavoro
Testare l'integrazione del webhook

Passaggio 1: Creare l'app Sales Commissions in Zoho Creator

In Zoho Creator, creare l'app Sales Commission con i seguenti campi:

Sales Rep
Deal Name
Customer Name
Opportunity Amount
Type of Business: New Business o Existing Business
Closing Date
Sales Commission

Per creare un'applicazione in Zoho Creator consultare la guida online

Passaggio 2: Configurare il Webhook

Selezionare i seguenti campi dal modulo Deal durante la configurazione dei parametri definiti dall'utente:

Deal Name
Closing Date
Type
Record Owner
Amount

Nel Webhook, specificare i seguenti dettagli:

URL to Notify:

https://creator.zoho.com/api/xml/write - metodo POST

Parametri Raw- Body type (XML, Text, JSON o HTML)

<ZohoCreator>
<applicationlist>
<application name='sales-commissions'>
<formlist>
<form name='Commissions'>
<add>
<field name='Name'>
<value> ${Potentials.Potential Name} </value>
</field>
<field name='Closed_Amount'>
<value> ${Potentials.Amount} </value>
</field>
<field name='Closing_Date'>
<value> ${Potentials.Closing Date} </value>
</field>
<field name='Customer_Name'>
<value> ${Accounts.Account Name} </value>
</field>
<field name='Type_of_Business'>
<value> ${Potentials.Type} </value>
</field>
<field name='Sales_Rep'>
<value> ${Potentials.Potential Owner} </value></field>
</add>
</form>
</formlist>
</application>
</applicationlist>
</ZohoCreator>

Nota

Nella stringa XML sopra, name rappresenta il campo nell'app Zoho Creator e il value indica i dati da inviare da Zoho CRM.
<applicaton name> è il nome dell'applicazione che contiene il modulo in Zoho Creator. Ottenere il nome dell'applicazione dalla scheda Application Settings di Zoho Creator.
<form name> è il nome del modulo in cui si modificano i record in Zoho Creator. Ottenere il nome del modulo dalle Form Settings del proprio account Zoho Creator.
Assicurarsi che il formato della data nell'app Creator sia nel formato yyyy-MM-dd. È possibile modificare il formato della data dalle Application Settings del proprio account Zoho Creator.

Parametri personalizzati:

Parametro	Descrizione
Authorization	Configurare una connessione con Creator nelle Connections sotto Developer Space e selezionare la stessa nel tipo di autorizzazione del webhook nel CRM. Consultare la guida di Creator per maggiori dettagli.
zc_ownername*	Specificare il nome del proprietario dell'applicazione del proprio account Creator.

Nota

Per recuperare dati da altre app verso Zoho Creator, è necessario specificare il nome utente e il tipo di autorizzazione. Per generare le informazioni API di Zoho, consultare la guida online

Passaggio 3: Configurare la regola del flusso di lavoro

Seguire questi passaggi nella pagina Workflow Rule:

Configurare i criteri del flusso di lavoro come:
- Type è New Business
- Stage è Closed Won
Fare clic su Next.

Selezionare il webhook come azione istantanea.
Nel popup Call Webhook , selezionare il webhook richiesto dall'elenco e fare clic su Associate.
Salvare la regola del flusso di lavoro.

Associare il Webhook alla regola del flusso di lavoro

Passaggio 4: Testare l'integrazione

Aggiungere una trattativa di test nel CRM con i campi Type e Stage impostati rispettivamente come New Business e Closed Won. Durante l'inserimento dei dati di test, assicurarsi che siano inseriti anche Amount, Closing Date, Record Owner, Account Name e Deal Name.
Aprire l'app Sales Commission in Zoho Creator e verificare i dati del CRM.
Se non sono stati ricevuti dati, modificare la configurazione del webhook e continuare i test. Dopo aver completato con successo i test, rimuovere le voci di test e distribuire questa integrazione agli utenti del CRM.