Webhook·Facile 12 minAggiornato: 30 marzo 2026

Integrare Qualsiasi Dispositivo con Webhook Shangrilux

Usa i webhook generici per collegare serrature, sensori, sistemi PMS e qualsiasi piattaforma a Shangrilux.

Come Funzionano i Webhook

Un webhook è una notifica HTTP inviata automaticamente da un sistema a un URL configurato quando accade un evento specifico. Shangrilux supporta webhook sia in entrata (da dispositivi esterni → Shangrilux) sia in uscita (da Shangrilux → sistemi esterni).

Webhook in Uscita (Shangrilux → Sistema Esterno)

Crea un endpoint ricevitore

Il tuo sistema deve esporre un endpoint HTTPS pubblico capace di ricevere POST JSON. Il server deve rispondere con HTTP 200 entro 10 secondi.

Configura il webhook in Shangrilux

Admin → Integrazioni → Webhook → Nuovo Webhook → inserisci URL, segreto HMAC (opzionale ma raccomandato), e seleziona gli eventi da notificare.

Evento	Descrizione	Payload chiave
booking.confirmed	Prenotazione confermata	guest_name, checkin, checkout, access_code
booking.checkin	Ospite entrato (check-in effettuato)	booking_id, guest_name, room
booking.checkout	Ospite uscito (check-out effettuato)	booking_id, checkout_time
access.granted	Accesso concesso a dispositivo	device_id, person, timestamp
access.denied	Accesso negato	device_id, reason, timestamp
device.offline	Dispositivo offline	device_id, last_seen

Verifica la firma HMAC

Ogni webhook in uscita include l'header X-Shangrilux-Signature per verificare l'autenticità:

python

import hmac, hashlib

def verify_shangrilux_webhook(payload_bytes: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode('utf-8'),
        payload_bytes,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

# Nel tuo handler Flask/FastAPI:
# sig = request.headers.get('X-Shangrilux-Signature')
# verify_shangrilux_webhook(request.data, sig, "TUO_SEGRETO")

Webhook in Entrata (Sistema Esterno → Shangrilux)

Endpoint Shangrilux per eventi dispositivi

Invia eventi da qualsiasi dispositivo all'endpoint universale Shangrilux:

bash

# Notifica apertura porta da sistema esterno
curl -X POST https://app.shangrilux.com/api/webhook/generic?slug=IL-TUO-SLUG \
  -H "Authorization: Bearer TUO_WEBHOOK_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "device_id": "door_main_entrance",
    "event": "access_granted",
    "person_id": "booking_abc123",
    "timestamp": "2026-06-01T14:03:27Z",
    "metadata": {
      "method": "pin",
      "duration_ms": 450
    }
  }'

Formato payload di risposta Shangrilux

Shangrilux risponde con JSON contenente il risultato dell'elaborazione e le azioni eseguite:

json

{
  "received": true,
  "event_id": "evt_k92jx01",
  "booking_matched": true,
  "booking_id": "bk_abc123",
  "actions_triggered": ["log_access", "notify_admin"],
  "timestamp": "2026-06-01T14:03:28Z"
}

Consiglio: Usa ngrok o cloudflared tunnel per testare i webhook durante lo sviluppo senza esporre la rete di produzione. Esempio: ngrok http 8000 → usa l'URL ngrok come endpoint di test in Shangrilux.

#webhook#api#generic#integration#hmac