Panoramica

Ce contenu n’est pas encore disponible dans votre langue.

Invece di interrogare l’API ogni minuto per sapere se è successo qualcosa, fatti chiamare: registri un indirizzo e Aitrack manda un POST quando l’evento accade. Si configurano anche da Impostazioni → Moduli → API e Webhook, oppure via API.

Gli eventi che puoi ricevere sono gli stessi che fanno scattare le automazioni (ingresso e uscita da un’area, accensione, sosta, allarmi…). Un endpoint iscritto a * li riceve tutti.

Configurare un endpoint

POST /api/webhooks — stessa autenticazione del resto dell’API (sessione utente o chiave API con header X-API-Key).

Campo	Vincoli
`url`	URL valido, solo `https://`, max 2048 caratteri
`description`	opzionale, max 256 caratteri
`events`	array di stringhe, almeno 1 (usa `*` per tutti gli eventi)
`retry_policy`	`none` \| `fixed` \| `exponential` (default `exponential`)
`max_retries`	intero 0–10 (default 5)

Limite: massimo 100 webhook per owner.

Alla creazione viene generato un signing secret, mostrato una sola volta: serve a verificare la firma di ogni consegna. In lettura il secret non viene mai restituito; si può ruotare con POST /api/webhooks/:id/rotate-secret.

curl -X POST https://api.aitrack.it/api/webhooks \
  -H "X-API-Key: $AITRACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://tuo-dominio.example.com/webhooks/aitrack",
    "description": "Sincronizzazione flotta",
    "events": ["geofence_enter", "geofence_exit"],
    "retry_policy": "exponential",
    "max_retries": 5
  }'

const res = await fetch('https://api.aitrack.it/api/webhooks', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.AITRACK_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://tuo-dominio.example.com/webhooks/aitrack',
    description: 'Sincronizzazione flotta',
    events: ['geofence_enter', 'geofence_exit'],
    retry_policy: 'exponential',
    max_retries: 5,
  }),
});
const { webhook } = await res.json();
console.log(webhook); // il campo "secret" arriva SOLO in questa risposta

res = requests.post(
    "https://api.aitrack.it/api/webhooks",
    headers={"X-API-Key": api_key, "Content-Type": "application/json"},
    json={
        "url": "https://tuo-dominio.example.com/webhooks/aitrack",
        "description": "Sincronizzazione flotta",
        "events": ["geofence_enter", "geofence_exit"],
        "retry_policy": "exponential",
        "max_retries": 5,
    },
    timeout=10,
)
webhook = res.json()["webhook"]  # "secret" arriva solo in questa risposta

Endpoint di gestione

Metodo	Percorso	Descrizione
`POST`	`/api/webhooks`	Crea un endpoint
`GET`	`/api/webhooks`	Elenca gli endpoint dell’owner
`GET`	`/api/webhooks/:id`	Dettaglio (senza secret)
`PUT`	`/api/webhooks/:id`	Aggiorna (l’URL viene ri-validato)
`DELETE`	`/api/webhooks/:id`	Elimina
`POST`	`/api/webhooks/:id/test`	Invia un evento `ping` solo a quell’endpoint
`POST`	`/api/webhooks/:id/rotate-secret`	Ruota il signing secret
`GET`	`/api/webhooks/:id/deliveries`	Storico consegne, paginato
`GET`	`/api/webhooks/metrics/summary`	Metriche 24h (tasso di successo, p95…)
`GET`	`/api/webhooks/dead-letter/list`	Consegne esaurite (dead-letter)
`POST`	`/api/webhooks/deliveries/:deliveryId/replay`	Ri-accoda una consegna fallita o esaurita

Tutti gli endpoint sono filtrati per owner: non vedi né tocchi i webhook di nessun altro.

Payload

Ogni evento consegnato ha lo stesso corpo:

{
  "id": "evt_9f2c1a4b7e6d4f0a9b3c2d1e0f8a7b6c",
  "type": "geofence_enter",
  "created_at": "2026-07-14T09:00:00.000Z",
  "data": { }
}

data cambia forma in base al tipo di evento. id è stabile per evento: se ti arriva due volte lo stesso id (retry), scartalo — vedi Consegna e retry.