Webhook inbound

I webhook inbound consentono a un workspace di ricevere eventi da sistemi esterni e mapparli nel contratto di invio di template transazionale di Switchbord.

Impostazioni predefinite di sicurezza

Le nuove configurazioni webhook sono disabilitate e in dry-run per impostazione predefinita. Un dry-run registra l’esecuzione inbound, verifica la firma, valida la mappatura e memorizza la richiesta transazionale mappata senza accodare un invio effettivo. I segreti vengono generati una sola volta. Switchbord memorizza solo un hash SHA-256 e un breve prefisso per la visualizzazione. Le risposte di elenco non includono mai il segreto grezzo. Dopo la creazione, non inviare mai il segreto grezzo a Switchbord; usalo solo per produrre le firme delle richieste.

Endpoint

Ogni configurazione ottiene un URL generato:

POST /api/v1/inbound-webhooks/{slug}

L’endpoint risolve il workspace e la configurazione del webhook dallo slug dell’URL. I campi del payload non vengono mai considerati attendibili per la risoluzione del tenant.

Autenticazione

Le richieste devono includere una firma HMAC con timestamp calcolata sul corpo grezzo esatto della richiesta. Non includere il segreto webhook grezzo negli header, nei parametri di query o nel payload.

X-Switchbord-Signature: t=<timestamp unix in secondi>,v1=<hmac sha256 hex>
Idempotency-Key: id-evento-esterno-opzionale

L’HMAC v1 firma {timestamp}.{rawBody} con il segreto one-time generato alla creazione del webhook. I timestamp devono trovarsi entro cinque minuti dall’orologio di Switchbord per ridurre il rischio di replay. Sono accettate più voci v1, così i mittenti possono ritentare durante la rotazione delle chiavi, ma almeno una deve corrispondere. Esempio di generazione della firma:

import { createHash, createHmac } from "node:crypto";

const timestamp = Math.floor(Date.now() / 1000);
const secretHash = createHash("sha256").update(secret).digest("hex");
const digest = createHmac("sha256", secretHash)
  .update(`${timestamp}.${rawBody}`)
  .digest("hex");
const signature = `t=${timestamp},v1=${digest}`;

La verifica della firma usa un confronto a tempo costante (timing-safe) e avviene prima della mappatura o dell’accodamento.

Mappatura

Il builder in Settings è il modo consigliato per creare le mappature. Carica i template Utility approvati, mostra le variabili body/button/header di cui ogni template ha bisogno e ti consente di mappare ogni campo da un percorso del payload, un valore letterale o un valore JSON. Le mappature a runtime supportano valori dot-path legacy ed espressioni esplicite:

{
  "to": "path:customer.phone",
  "templateName": "literal:payment_receipt_document",
  "templateLocale": "literal:it",
  "externalId": "path:receipt.id",
  "parameters.header.document.link": "path:receipt.pdf",
  "parameters.header.document.filename": "literal:receipt.pdf",
  "parameters.body.1": "path:customer.first_name",
  "parameters.body.2": "path:receipt.number"
}

Prefissi delle espressioni:

Prefisso	Significato
`path:`	Risolve un dot path dal payload JSON inbound.
`literal:`	Usa il testo dopo il prefisso come valore.
`json:`	Analizza il testo dopo il prefisso come JSON.
nessun prefisso	Ricerca dot-path legacy dal payload inbound.

I target delle mappature non possono contenere __proto__, prototype o constructor. Switchbord rifiuta i target non sicuri prima dell’anteprima o dell’elaborazione del webhook. I valori templateName e templateLocale configurati sovrascrivono i valori mappati. Le nuove configurazioni create tramite Settings sono limitate al template Utility approvato selezionato.

Log delle esecuzioni

Ogni richiesta ricevuta per una configurazione abilitata registra un’esecuzione con header redatti, metadata sulla forma del payload, diagnostica della richiesta mappata sanificata, stato ed errori. I payload grezzi del cliente, i numeri di telefono dei destinatari e i valori delle variabili del template non vengono memorizzati nei log delle esecuzioni per impostazione predefinita. Le firme non valide vengono registrate come esecuzioni fallite e restituiscono 401, ma non riservano chiavi di idempotenza verificate. I possibili stati di esecuzione includono verified, dry_run, queued, failed e skipped_duplicate.

Limitazione attuale

La base runtime può eseguire il servizio di invio di template transazionale quando una configurazione è abilitata, ma le configurazioni create tramite Settings sono attualmente forzate in modalità dry-run disabilitata e non possono essere promosse tramite l’API pubblica di Settings. Una richiesta firmata verso una configurazione disabilitata restituisce 404 webhook_not_found_or_disabled. La promozione live è bloccata a livello server finché non viene rilasciato un flusso di promozione verificato dai log delle esecuzioni. Usa Invii di template transazionali per gli invii in produzione oggi.

Riferimento API

Impostazioni predefinite di sicurezza

Endpoint

Autenticazione

Mappatura

Log delle esecuzioni

Limitazione attuale

Guide di integrazione

​Impostazioni predefinite di sicurezza

​Endpoint

​Autenticazione

​Mappatura

​Log delle esecuzioni

​Limitazione attuale

​Guide di integrazione

Impostazioni predefinite di sicurezza

Endpoint

Autenticazione

Mappatura

Log delle esecuzioni

Limitazione attuale

Guide di integrazione