Ingestion webhook

L'ingestion webhook è un singolo endpoint che riceve eventi tipizzati dal tuo sistema (lead/created, deal/updated, …) e li scrive nel CRM Audin, ereditando gli stessi effetti delle scritture native: automazioni (workflow), assegnazione del lead, storico delle modifiche. Ogni evento porta un tuo identificativo (external_id) con cui Audin fa upsert: lo stesso record nel tuo sistema corrisponde sempre allo stesso record in Audin.

Quando usarlo

L'ingestion webhook è la scelta giusta quando la fonte di verità è il tuo sistema e vuoi un canale unico, idempotente e tipizzato per riversare i cambiamenti in Audin.

Autenticazione

L'ingestion webhook richiede due fattori, entrambi appartenenti allo stesso Account:

1. Un token segreto per-Account nell'URL — l'endpoint è POST https://api.audin.ai/webhooks/ingest/<token>, dove <token> (formato aud_ing_…) è una credenziale dedicata all'ingestion.
2. L'Account API Key nell'header X-API-Key (la stessa usata da tutta l'API REST partner, vedi Autenticazione).

Se il token e l'API Key non si riferiscono allo stesso Account — o il token è mancante/errato — la richiesta viene rifiutata con 403 webhook_auth_failed.

Le scritture che richiedono un riferimento a un utente (es. createdBy, ownerId) sono risolte automaticamente sull'owner dell'Account.

curl -X POST https://api.audin.ai/webhooks/ingest/<token> \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "id": "evt_001", "type": "lead/created", "data": { "external_id": "L-42" } }'

Il token di ingestion

Il token (aud_ing_…) è un segreto: chi lo possiede insieme all'API Key può scrivere nel tuo CRM. Trattalo come una credenziale — non condividerlo, non inserirlo in URL pubblici o log, conservalo in modo sicuro lato server.

• Ottenerlo / consultarlo: dalla pagina Sviluppatori → Webhook di ingestion del dashboard. L'URL completo (token incluso) è ora sempre visibile e copiabile da quella pagina: non è più mostrato una sola volta alla generazione, puoi recuperarlo in qualsiasi momento. Resta comunque un segreto: trattalo come una credenziale.
• Rotazione: rigenerare il token invalida immediatamente l'URL precedente. Aggiorna il sistema sorgente con il nuovo URL prima — o subito dopo — la rigenerazione per evitare interruzioni.

Envelope dell'evento

Ogni richiesta è un singolo evento (non un batch) con questa struttura:

{
  "id": "evt_8f3a",
  "type": "lead/updated",
  "occurred_at": "2026-06-16T10:00:00Z",
  "suppress_triggers": false,
  "data": {
    "external_id": "L-42",
    "email": "mario@acme.example.com"
  }
}

Tipi di evento

lead/created e lead/updated

Stesso schema data per entrambi:

{
  "id": "evt_lead_1",
  "type": "lead/created",
  "data": {
    "external_id": "L-42",
    "full_name": "Mario Rossi",
    "email": "mario@acme.example.com",
    "phone_number": "+393334445566",
    "custom_params": { "origine": "fiera-2026", "interesse": "impianti" }
  }
}

deal/created e deal/updated

{
  "id": "evt_deal_1",
  "type": "deal/created",
  "data": {
    "external_id": "D-77",
    "title": "Preventivo impianto",
    "amount": 3500,
    "currency": "EUR",
    "lead_external_id": "L-42",
    "stage_name": "Nuovo",
    "owner_name": "Giulia Bianchi"
  }
}

comment/created

{
  "id": "evt_comment_1",
  "type": "comment/created",
  "data": {
    "external_id": "C-9",
    "content": "Il cliente preferisce essere richiamato di pomeriggio.",
    "author_name": "Reception",
    "lead_external_id": "L-42"
  }
}

Risoluzione stage e owner

Per i deal puoi indicare stage e assegnatario in due modi, mai con un default silenzioso:

• Per UUID (stage_id / owner_id) — autoritativo. È l'identificativo esatto della risorsa Audin.
• Per nome (stage_name / owner_name) — Audin risolve il nome all'interno del tuo Account.

Se un nome è ambiguo (più corrispondenze) o non trovato, l'evento viene rifiutato con un errore esplicito (unresolved_reference): non viene mai applicato un valore di ripiego.

Gli stage delle pipeline e gli operatori del tuo Account sono visibili nel dashboard. Gli UUID corrispondenti si recuperano via API REST con GET /pipelines (stage di una pipeline) e GET /platform-users (operatori) — vedi Lettura & sistema e Pipeline & deal.

Ordine e semantica

La semantica created / updated è stretta sull'external_id:

Poiché deal e commenti si agganciano a un'entità padre, invia gli eventi in quest'ordine:

1. lead/*
2. deal/* (richiede il lead padre)
3. comment/* (richiede il lead o il deal padre)

Idempotency & retry

L'id dell'envelope è la chiave di idempotency, per Account:

• Se un evento con lo stesso id è già stato processato con successo, Audin non riesegue l'azione e risponde con lo stesso esito, marcato "deduplicated": true.
• Un evento fallito può essere ritentato con lo stesso id: alla riuscita verrà processato normalmente.

Questo rende sicuro il retry su timeout o errore di rete: usa sempre lo stesso id per lo stesso evento sorgente.

Backfill

Per importazioni storiche (backfill) imposta suppress_triggers: true (o l'header X-Suppress-Triggers: true): gli eventi vengono scritti senza attivare automazioni né assegnazioni automatiche. Utile per ricaricare uno storico senza generare notifiche, chiamate o workflow indesiderati.

curl -X POST https://api.audin.ai/webhooks/ingest/<token> \
  -H "X-API-Key: $API_KEY" \
  -H "X-Suppress-Triggers: true" \
  -H "Content-Type: application/json" \
  -d '{ "id": "backfill_001", "type": "lead/created", "data": { "external_id": "L-1001" } }'

Risposta

In caso di successo l'endpoint risponde 200 con il riepilogo dell'evento processato:

{
  "status": "processed",
  "entity": "Lead",
  "id": "9b1c2d3e-…",
  "outcome": "created",
  "deduplicated": false
}

Codici di errore

Gli errori dell'ingestion webhook usano l'envelope con code/message (la stessa forma delle rotte autenticate con API Key):

{
  "success": false,
  "error": {
    "code": "unresolved_reference",
    "message": "Stage \"Nuovo\" non trovato"
  }
}

Esempio end-to-end

Riversa un lead, la sua opportunità e una nota — nell'ordine corretto:

# 1. Lead
curl -X POST https://api.audin.ai/webhooks/ingest/<token> \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{
    "id": "evt_l_1",
    "type": "lead/created",
    "data": {
      "external_id": "L-42",
      "full_name": "Mario Rossi",
      "email": "mario@acme.example.com",
      "phone_number": "+393334445566"
    }
  }'

# 2. Deal agganciato al lead via lead_external_id
curl -X POST https://api.audin.ai/webhooks/ingest/<token> \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{
    "id": "evt_d_1",
    "type": "deal/created",
    "data": {
      "external_id": "D-77",
      "title": "Preventivo impianto",
      "amount": 3500,
      "currency": "EUR",
      "lead_external_id": "L-42",
      "stage_name": "Nuovo"
    }
  }'

# 3. Commento sul lead
curl -X POST https://api.audin.ai/webhooks/ingest/<token> \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{
    "id": "evt_c_1",
    "type": "comment/created",
    "data": {
      "external_id": "C-9",
      "content": "Richiamare di pomeriggio.",
      "author_name": "Reception",
      "lead_external_id": "L-42"
    }
  }'

// L'URL contiene il token segreto per-Account (aud_ing_…) ottenuto dalla
// pagina "Sviluppatori → Webhook di ingestion": tienilo lato server.
const INGEST_URL = process.env.AUDIN_INGEST_WEBHOOK_URL; // …/webhooks/ingest/aud_ing_…

const ingest = (event) =>
  fetch(INGEST_URL, {
    method: "POST",
    headers: {
      "X-API-Key": process.env.AUDIN_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(event),
  }).then((r) => r.json());

// 1. Lead → 2. Deal → 3. Commento (l'ordine conta: deal e commento
// richiedono che il padre esista già).
await ingest({
  id: "evt_l_1",
  type: "lead/created",
  data: {
    external_id: "L-42",
    full_name: "Mario Rossi",
    email: "mario@acme.example.com",
    phone_number: "+393334445566",
  },
});

await ingest({
  id: "evt_d_1",
  type: "deal/created",
  data: {
    external_id: "D-77",
    title: "Preventivo impianto",
    amount: 3500,
    currency: "EUR",
    lead_external_id: "L-42",
    stage_name: "Nuovo",
  },
});

await ingest({
  id: "evt_c_1",
  type: "comment/created",
  data: {
    external_id: "C-9",
    content: "Richiamare di pomeriggio.",
    author_name: "Reception",
    lead_external_id: "L-42",
  },
});

Prossimo passo