Guida utente: webhook

Guida utente: webhook

🔐 Introduzione all'utilizzo dei webhook

La nostra piattaforma ti consente di configurare webhook per ricevere aggiornamenti automatici sugli eventi chiave relativi ai tuoi ordini e incidenti. Questo ti permette di mantenere i tuoi sistemi sincronizzati senza la necessità di query manuali.

📌 Cosa sono i Webhook?

Un webhook è una chiamata automatica che il nostro sistema effettua a un URL da te configurato ogni volta che si verifica un evento rilevante (ad esempio, una modifica dello stato di un ordine o di un incidente). In questo modo, il tuo sistema può reagire immediatamente a questi cambiamenti.

🔑 Configurazione iniziale

Per iniziare a utilizzare i webhook:
  1. Vai alla sezione Il mio account > Token di accesso .
  2. Crea una chiave API con autorizzazioni sui tuoi ordini e problemi.
  3. Configura due endpoint (URL pubblici):
  4. Uno per ricevere aggiornamenti sullo stato dell'ordine .
  5. Un altro per ricevere aggiornamenti sullo stato dell'incidente .

✅ Sicurezza: firme HMAC (opzionali per ora)

Per convalidare l'autenticità degli eventi ricevuti, ogni webhook può includere una firma digitale nell'intestazione:
  1. Intestazione : X-Dropea-Hmac-Sha256
  2. Contenuto : un hash SHA256 generato utilizzando il corpo del POST (payload) e la chiave API corrispondente come chiave segreta.
Ciò consente di verificare che la richiesta provenga effettivamente dal nostro sistema e che non sia stata modificata, in modo simile a quanto fa Shopify con il suo sistema di webhook .

⚠️ Importante: la convalida della firma è attualmente facoltativa, ma se ne consiglia l'implementazione per rafforzare la sicurezza.

🛍️ Aggiornamento sullo stato dell'ordine

Quando lo stato di un ordine viene aggiornato, il sistema invia una notifica al webhook configurato con la seguente struttura di eventi:

❌ Esempio 1: l'ordine passa da Confermato ad Annullato (da Ricevere)
  1. {"topic":"order:status_update","order_id":265494,"prev_status":"confermato","new_status":"annullato","updated_at":"29/05/2025 14:14:58"}

✅ Esempio 2: l'ordine passa da In sospeso a Confermato (da ricevere)
  1. {"topic":"order:status_update","order_id":265494,"prev_status":"in sospeso","new_status":"confermato","updated_at":"29/05/2025 14:14:58"}

🔁 Esempio 3: l'ordine passa da Errore a In attesa (da ricevere)
  1. {"argomento":"ordine:aggiornamento_stato",
  2. "order_id":265496,"prev_status":"errore","new_status":"in sospeso","updated_at":"2025-05-29 14:38:05"}

🛠️ Aggiornamento sull'incidenza

📌 Esempio: l'incidente passa da In sospeso a Gestito dal cliente (da ricevere)
  1. {
  2. "argomento": "incidenza:aggiornamento_stato",
  3. "nuovo_stato": "gestito dal cliente",
  4. "aggiornato_alle": "2025-02-13 14:23:56",
  5. "prev_status": "in sospeso",
  6. "incidence_id": 189044
  7. }

🔄 Esempio 2: l'incidente passa da In sospeso a Soluzione inviata
  1. {
  2. "argomento": "incidenza:aggiornamento_stato",
  3. "incidence_id": 265494,
  4. "prev_status": "client_managed",
  5. "nuovo_stato": "invio_risoluzione",
  6. "aggiornato_alle": "29/05/2025 16:10:45"
  7. }

✅ Esempio 3: l'incidente passa da Soluzione inviata a Risolto (Payload da ricevere)
  1. {
  2. "argomento": "incidenza:aggiornamento_stato",
  3. "incidence_id": 265494,
  4. "prev_status": "soluzione_invia",
  5. "new_status": "risolto",
  6. "aggiornato_alle": "29/05/2025 17:42:30"
  7. }

📌 Dettagli per campo


Campo
Tipo Descrizione
argomento
corda
Può essere "order:status_update" o "incidence:status_update" , a seconda dell'origine dell'evento.
ID ordine
intero
ID dell'ordine interessato. Presente solo se l'argomento è order:status_update.
incidenza_id
intero
ID del problema interessato. Presente solo se l'argomento è incident:status_update.
stato_precedente
corda
Stato precedente dell'oggetto. Ad esempio, "in sospeso", "confermato", "errore".
nuovo_stato
corda
Nuovo stato dopo la modifica.
aggiornato_a
data
Data e ora della modifica. Questo campo è nel fuso orario Europa/Madrid , ovvero:
— UTC+2 in estate (ora legale)
— UTC+1 in inverno (ora standard)