Webhook

​

Quando usare i webhook

• Moduli del sito: aggiungere un lead appena qualcuno compila un modulo di contatto
• Applicazioni su misura: integrare i tuoi sistemi software esistenti
• Strumenti di terze parti: collegare servizi non supportati direttamente
• Importazione in tempo reale: aggiungere i lead nel momento in cui vengono generati

​

Configurare il webhook

​

1. Ottieni la tua API key

​

2. Endpoint API

POST https://api.whappy.ai/v1/lead

​

3. Header obbligatori

Content-Type: application/json
X-API-Key: la-tua-api-key

​

Formato della richiesta

​

Campi obbligatori

• name: nome completo del lead
• phone: numero di telefono (con prefisso internazionale)

​

Campi facoltativi

• email: indirizzo email del lead
• company: nome dell’azienda
• source: da dove arriva il lead (es. “Sito”, “Facebook”)
• custom_fields: dati aggiuntivi come coppie chiave-valore

​

Esempio di corpo della richiesta

{
  "name": "Mario Rossi",
  "phone": "+393441234567",
  "email": "mario@esempio.it",
  "company": "Acme Srl",
  "source": "Sito",
  "custom_fields": {
    "budget": "10000",
    "interest": "Prodotto A"
  }
}

​

Esempi di codice

curl -X POST https://api.whappy.ai/v1/lead \
-H "Content-Type: application/json" \
-H "X-API-Key: la-tua-api-key" \
-d '{
"name": "Mario Rossi",
"phone": "+393441234567",
"email": "mario@esempio.it",
"company": "Acme Srl",
"source": "Sito"
}'

fetch('https://api.whappy.ai/v1/lead', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-API-Key': 'la-tua-api-key'
},
body: JSON.stringify({
name: 'Mario Rossi',
phone: '+393441234567',
email: 'mario@esempio.it',
company: 'Acme Srl',
source: 'Sito'
})
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Errore:', error));

import requests
import json

url = "https://api.whappy.ai/v1/lead"
headers = {
"Content-Type": "application/json",
"X-API-Key": "la-tua-api-key"
}
payload = {
"name": "Mario Rossi",
"phone": "+393441234567",
"email": "mario@esempio.it",
"company": "Acme Srl",
"source": "Sito"
}

response = requests.post(url, headers=headers, data=json.dumps(payload))
print(response.json())

​

Formato della risposta

​

Risposta positiva

{
  "status": "success",
  "data": {
    "id": "lead_12345",
    "name": "Mario Rossi",
    "phone": "+393441234567",
    "created_at": "2026-01-15T10:30:00Z"
  }
}

​

Risposta di errore

{
  "status": "error",
  "message": "Formato del numero di telefono non valido"
}

​

Usare i campi personalizzati

{
  "name": "Mario Rossi",
  "phone": "+393441234567",
  "custom_fields": {
    "budget": "50000",
    "timeline": "3 mesi"
  }
}

Ciao {{name}}, vedo che cerchi una soluzione con un budget di {{budget}} e tempistiche di {{timeline}}. Parliamone!

​

Provare il webhook

1. Usa l’API key della tua dashboard
2. Fai una semplice richiesta cURL per verificare la connettività
3. Controlla la sezione Lead per confermare che il lead sia stato aggiunto
4. Verifica che la campagna elabori il lead correttamente

​

Casi d’uso comuni

​

Moduli di contatto del sito

// Dopo l'invio del modulo
const formData = {
  name: document.getElementById('name').value,
  phone: document.getElementById('phone').value,
  email: document.getElementById('email').value,
  source: 'Modulo di contatto del sito'
};

// Invio a Whappy
fetch('https://api.whappy.ai/v1/lead', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'la-tua-api-key'
  },
  body: JSON.stringify(formData)
});

​

Buone pratiche di sicurezza

• Usa solo HTTPS per tutte le richieste
• Conserva le API key in modo sicuro (variabili d’ambiente, non nel codice)
• Valida i dati prima di inviarli, per prevenire errori
• Gestisci gli errori con eleganza nella tua applicazione
• Monitora l’uso del webhook per individuare attività anomale

​

Risoluzione dei problemi

• Controlla che l’API key sia corretta
• Verifica che il numero includa il prefisso internazionale
• Assicurati che la campagna sia in esecuzione

• Verifica che tutti i campi obbligatori siano presenti
• Controlla che il formato della richiesta corrisponda agli esempi
• Verifica che la tua API key abbia i permessi corretti