Configura i webhook

Un webhook invia una richiesta HTTP a un URL che scegli ogni volta che succede qualcosa nel tuo salone, per esempio quando viene creato un appuntamento o aggiornato un cliente. Usalo per mantenere un altro sistema sincronizzato con Softalon.

Crea un webhook

1. 1

   Passaggio 1 di 4

   Apri Webhook

   Vai su Impostazioni › Sviluppatori › Webhook e fai clic su Crea webhook.

2. 2

   Passaggio 2 di 4

   Inserisci la destinazione

   Compila URL di destinazione, per esempio https://example.com/webhook, e facoltativamente una Descrizione per riconoscerlo in seguito.

3. 3

   Passaggio 3 di 4

   Scegli gli argomenti

   In Argomenti, seleziona gli eventi che vuoi. La scheda Tutti gli argomenti elenca ogni argomento disponibile, e Argomenti selezionati mostra quelli che hai scelto. Il tuo URL riceve solo gli argomenti selezionati.

4. 4

   Passaggio 4 di 4

   Salva

   Fai clic su Crea webhook.

   Vedrai:

   Webhook creato, e il webhook compare nella tabella con l'interruttore dello stato attivo.

Argomenti

Gli argomenti hanno il formato resource.action. Sono disponibili:

Per il significato di ogni trigger, vedi I trigger delle automazioni spiegati.

Cosa invia Softalon

Ogni evento è una richiesta POST con un corpo JSON:

{
  "topic": "booking/appointment.created",
  "event": {
    "id": "...",
    "type": "booking/appointment.created",
    "resource": "booking/appointment",
    "resourceId": "...",
    "salonId": "...",
    "data": {
      "object": { "...": "the full object" },
      "previousAttributes": { "...": "changed fields, for updates" }
    }
  }
}

La richiesta ha questi header:

Verifica la firma

Ogni webhook ha un secret. Softalon firma il corpo della richiesta con il secret usando HMAC-SHA256 e invia il risultato esadecimale in X-Webhook-Signature. Calcola lo stesso valore dal corpo grezzo della richiesta e confrontali. Se non corrispondono, ignora la richiesta.

const crypto = require("crypto");

function isValid(rawBody, header, secret) {
  const expected = "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(header));
}

Per gestire il secret, usa i pulsanti nella colonna Secret:

• Il pulsante con l'occhio mostra il secret completo, e il pulsante di copia lo copia.
• Il pulsante di rigenerazione crea subito un nuovo secret. Il vecchio secret smette di funzionare immediatamente, quindi aggiorna il tuo sistema nello stesso momento.

Invii e nuovi tentativi

• Il tuo URL deve rispondere con un codice di stato 2xx entro 10 secondi. Qualsiasi altra risposta conta come errore.
• Un invio non riuscito viene ritentato, fino a 5 tentativi in totale. Le attese tra i tentativi crescono: circa 30 secondi, 1 minuto, 2 minuti e 4 minuti.
• Usa X-Webhook-Delivery-Id per ignorare un invio che hai già elaborato.

Ogni invio ha uno di questi stati:

L'app non mostra ancora un registro degli invii. Puoi leggere gli invii tramite l'API all'indirizzo GET /v1/salons/:salonId/webhook-endpoints/:webhookEndpointId/deliveries. Vedi Crea un'app API.

Modifica, sospendi o elimina un webhook

• Sospendi: disattiva l'interruttore nella colonna Stato.
• Modifica: apri il menu della riga e scegli Aggiorna.
• Elimina: apri il menu della riga e scegli Elimina.

I webhook inviano solo mentre il tuo salone ha un abbonamento attivo, in prova o scaduto su un piano che include i webhook.