Collega il tuo prodotto a Fabiana

Avvisa Fabiana quando qualcuno si registra o fa qualcosa nel tuo prodotto. Lei tiene il contatto aggiornato e le tue automazioni inviano l’email giusta al momento giusto.

Autenticazione

Crea una chiave in Impostazioni → Chiavi API (piani Pro e Business). Viene mostrata una sola volta. Inviala in ogni richiesta:

Authorization: Bearer fab.…

L’URL di base è https://api.getfabiana.com. Richieste e risposte sono in JSON. Ogni organizzazione può fare 300 richieste al minuto.

Inviare eventi

Una chiamata per ogni cosa che succede. Fabiana trova il contatto per email o telefono, oppure lo crea, e salva le proprietà sul contatto come campi personalizzati.

curl -X POST https://api.getfabiana.com/v1/events \
  -H "Authorization: Bearer $FABIANA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "signed_up",
    "contact": { "email": "ana@example.com", "name": "Ana", "emailOptIn": true },
    "properties": { "plan": "pro", "seats": 3 }
  }'

{ "contactId": "6f1c…", "created": true }

Cosa succede dopo

L’evento compare nella cronologia del contatto.
Partono le automazioni con il trigger Arriva un evento, filtrate per nome dell’evento e proprietà.
Partono le automazioni con il trigger Cambia un campo personalizzato quando una proprietà cambia valore.
Le sequenze in attesa di questo evento vanno avanti; quelle che devono fermarsi con esso si fermano.
Un nuovo contatto avvia anche le automazioni Il contatto viene creato.

I nomi degli eventi usano lettere, cifre e _ . : -. Le proprietà sono semplici: fino a 50 testi, numeri o booleani.

Email dai tuoi eventi

Le automazioni possono avviare una sequenza email o inviare una singola email, scritta come testo o creata da un modello con il tuo logo e il tuo colore. Oggetto e testo possono usare {{first_name}}, {{name}}, {{email}} e qualsiasi proprietà come {{custom.plan}}. I passi di una sequenza possono attendere giorni o ore, attendere un evento o una proprietà, o diramarsi in base a una condizione.

Le email di marketing arrivano solo ai contatti che hanno accettato di riceverle o che sono già clienti, e contengono il link di disiscrizione. Invia emailOptIn: true quando la persona ha spuntato la casella nel tuo modulo di registrazione.

Una singola email segnata come Transazionale, sul conto o sulla richiesta della persona (un benvenuto, una ricevuta), parte senza quel consenso e senza link di disiscrizione. Non usarla mai per le promozioni.

Aggiungi il tuo dominio in Impostazioni → Invio email e copia i record DNS che compaiono. Una volta verificato, le email partono dal tuo indirizzo, firmate per il tuo dominio.

Contatti

POST	/v1/events	Registra qualcosa che un contatto ha fatto nel tuo prodotto
POST	/v1/contacts	Crea un contatto, o restituisce quello con la stessa email o lo stesso telefono
GET	/v1/contacts	Elenca i contatti, 50 alla volta (limit, cursor)
GET	/v1/contacts/{id}	Restituisce un contatto
PATCH	/v1/contacts/{id}	Aggiorna un contatto

curl -X POST https://api.getfabiana.com/v1/contacts \
  -H "Authorization: Bearer $FABIANA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "ana@example.com", "name": "Ana", "tags": ["trial"], "properties": { "plan": "pro" } }'

Il riferimento completo è nella descrizione OpenAPI, che la maggior parte degli strumenti API e degli assistenti di programmazione sa leggere.

Webhook

Aggiungi un endpoint in Impostazioni → Webhook e scegli gli eventi che ti interessano. Fabiana invia un POST per ognuno e riprova se il tuo server non risponde.

contact.created: È stato creato un contatto: da Fabiana, dal team, da un’importazione o dall’API
contact.updated: Un contatto è cambiato; changedFields indica cosa
contact.stage_changed: Un contatto è passato a un’altra fase della pipeline (inviato anche come deal.stage_changed)
lead.created: Fabiana ha raccolto un nuovo lead in una conversazione
lead.converted: Un contatto ha raggiunto per la prima volta la fase prenotato
deal.closed: Una trattativa è stata chiusa come vinta (inviato anche come deal.closed_won)
deal.closed_lost: Un contatto è passato alla fase perso
conversation.created: È iniziata una nuova conversazione (inviato anche come conversation.started)
message.received: Un cliente ha scritto su un canale qualsiasi
handoff.requested: Fabiana ha passato una conversazione al team (inviato anche come conversation.handoff)
handoff.claimed: Qualcuno del team ha preso in carico una conversazione
handoff.resolved: È stata risolta una conversazione presa in carico dal team
conversation.resolved: Una conversazione è stata segnata come risolta
conversation.closed: Una conversazione è stata archiviata
csat.submitted: Un cliente ha valutato una conversazione

{
  "event": "deal.closed",
  "organizationId": "…",
  "timestamp": "2026-10-29T10:00:00.000Z",
  "data": { "contactId": "…", "name": "Ana", "dealClosedValue": 1200, "dealClosedAt": "…", "stage": "booked" }
}

Verifica l’intestazione X-Fabiana-Signature con il corpo così com’è e il segreto del webhook:

import { createHmac, timingSafeEqual } from 'node:crypto'

function isFromFabiana(rawBody: string, header: string, secret: string): boolean {
  const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex')
  return header.length === expected.length && timingSafeEqual(Buffer.from(header), Buffer.from(expected))
}

Errori

400 la richiesta non è valida, 401 la chiave manca o è stata revocata, 403 il ruolo della chiave o il tuo piano non lo consentono, 404 il contatto non esiste, 429 troppe richieste. Il corpo contiene un message.

Domande? Scrivi a hello@getfabiana.com.