Webhooks

I webhooks ti notificano in tempo reale quando avvengono eventi in BladeCRM.

Come Funzionano

1. Configuri un URL endpoint
2. Selezioni gli eventi da ricevere
3. BladeCRM invia POST al tuo URL quando l'evento accade
4. Il tuo sistema elabora la notifica

Creare un Webhook

Da Dashboard

1. Impostazioni → Webhooks → Nuovo
2. Configura:
   • Nome: Identificativo
   • URL: Endpoint del tuo server
   • Eventi: Quali eventi ricevere
3. Salva

Via API

POST /api/v1/webhooks

{
  "name": "Notifiche Slack",
  "url": "https://tuo-server.com/webhook",
  "events": ["contact.created", "deal.won"]
}

Eventi Disponibili

Contatti

Evento	Descrizione
contact.created	Nuovo contatto
contact.updated	Contatto modificato
contact.deleted	Contatto eliminato

Aziende

Evento	Descrizione
company.created	Nuova azienda
company.updated	Azienda modificata
company.deleted	Azienda eliminata

Trattative

Evento	Descrizione
deal.created	Nuova trattativa
deal.updated	Trattativa modificata
deal.stage_changed	Cambio stadio
deal.won	Trattativa vinta
deal.lost	Trattativa persa
deal.deleted	Trattativa eliminata

Attività

Evento	Descrizione
activity.created	Nuova attività
activity.completed	Attività completata

Appuntamenti

Evento	Descrizione
appointment.created	Nuovo appuntamento
appointment.updated	Appuntamento modificato
appointment.cancelled	Appuntamento annullato

Dettagli eventi →

Payload

Ogni webhook invia un payload JSON:

{
  "event": "contact.created",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "id": 123,
    "first_name": "Mario",
    "last_name": "Rossi",
    "email": "mario@example.com"
  }
}

Dettagli payload →

Sicurezza

Firma HMAC

Ogni richiesta include un header di firma:

X-BladeCRM-Signature: sha256=abc123...

Verifica la firma per assicurarti che la richiesta provenga da BladeCRM.

Dettagli sicurezza →

Retry

Se il tuo server non risponde (timeout o errore):

• 1° retry: dopo 1 minuto
• 2° retry: dopo 5 minuti
• 3° retry: dopo 30 minuti
• Poi il webhook viene segnato come fallito

Log

Monitora i webhook in Impostazioni → Webhooks → Log:

• Richieste inviate
• Risposte ricevute
• Errori

Esempio Ricezione

Node.js (Express)

app.post('/webhook', (req, res) => {
  const event = req.body.event;
  const data = req.body.data;
  
  switch(event) {
    case 'contact.created':
      console.log('Nuovo contatto:', data);
      break;
    case 'deal.won':
      console.log('Trattativa vinta:', data);
      break;
  }
  
  res.status(200).send('OK');
});

PHP

$payload = json_decode(file_get_contents('php://input'), true);
$event = $payload['event'];
$data = $payload['data'];

switch($event) {
    case 'contact.created':
        // Gestisci nuovo contatto
        break;
}

http_response_code(200);

---

TIP

Usa i webhooks invece del polling per notifiche in tempo reale. È più efficiente e rispetta i rate limits.