> ## Documentation Index > Fetch the complete documentation index at: https://docs.switchbord.ai/llms.txt > Use this file to discover all available pages before exploring further. # Rollout dry-run dei webhook in entrata > Testa in sicurezza le mappature dei webhook in entrata prima che gli invii transazionali live vengano abilitati. I webhook in entrata sono intenzionalmente prudenti. Le nuove configurazioni sono disabilitate e in dry-run di default, e la promozione live è bloccata a livello server finché non viene rilasciato un flusso di promozione verificato tramite run-log. Usa questa guida per validare oggi in sicurezza un'integrazione webhook e capire cosa cambierà quando la promozione live verrà abilitata. ## Comportamento attuale | Fase | Supportata oggi | Comportamento | | ----------------------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Creazione configurazione | Sì | Crea una configurazione disabilitata e in dry-run e mostra il segreto di firma una sola volta. | | Anteprima guidata | Sì | Risolve le mappature del payload di esempio nel browser senza inviare un messaggio. | | Richiesta firmata all'endpoint creato da Impostazioni | Non ancora | Le configurazioni create da Impostazioni sono disabilitate; le richieste firmate restituiscono `404 webhook_not_found_or_disabled` finché i controlli di promozione verificata non vengono rilasciati. | | Invio live da webhook in entrata | La base esiste, promozione bloccata in Impostazioni/API | L'esecuzione a runtime è implementata per le configurazioni abilitate, ma la promozione da Impostazioni/API resta bloccata finché i controlli di promozione verificata non vengono rilasciati. | | Interfaccia di replay/promozione | Lavoro futuro | Tracciato separatamente sotto observability dei webhook e controlli di rollout. | Se hai bisogno di invii in produzione immediatamente, usa direttamente l'API [Invii di modelli transazionali](/it/api-reference/transactional-template-sends) con una chiave API e una chiave di idempotenza. Usa i webhook in entrata oggi per validare la mappatura nell'anteprima nel browser e per preparare il codice di firma per la futura promozione dry-run lato server. ## Passo 1: crea il webhook 1. Apri **Impostazioni → Integrazioni → Webhook e API**. 2. Clicca **Crea webhook**. 3. Seleziona un modello Utility approvato. 4. Mappa i campi richiesti. 5. Incolla un payload di esempio. 6. Clicca **Esegui anteprima dry-run**. 7. Crea il webhook solo dopo che l'anteprima ha esito positivo. Switchbord mostra il segreto di firma una sola volta. Copialo immediatamente e archivialo nello store dei segreti del sistema esterno. ## Passo 2: prepara le richieste firmate Puoi preparare ora il mittente esterno, ma le configurazioni webhook create da Impostazioni sono disabilitate oggi. Una richiesta all'URL generato restituirà `404 webhook_not_found_or_disabled` finché i controlli di promozione verificata non vengono rilasciati. Usa il corpo JSON grezzo esatto quando generi la firma. ```ts theme={null} import { createHash, createHmac } from "node:crypto"; const payload = { customer: { phone: "+393331234567", first_name: "Giulia" }, receipt: { id: "payment-receipt-R-1001", number: "R-1001", amount: "€ 240,00", pdf: "https://cdn.example.com/receipts/R-1001.pdf" } }; const rawBody = JSON.stringify(payload); const timestamp = Math.floor(Date.now() / 1000); const secretHash = createHash("sha256").update(webhookSecret).digest("hex"); const digest = createHmac("sha256", secretHash) .update(`${timestamp}.${rawBody}`) .digest("hex"); await fetch(webhookUrl, { method: "POST", headers: { "Content-Type": "application/json", "X-Switchbord-Signature": `t=${timestamp},v1=${digest}`, "Idempotency-Key": payload.receipt.id }, body: rawBody }); ``` ## Passo 3: ispeziona l'anteprima nel browser oggi Oggi, il passo di validazione supportato è l'anteprima nel browser del builder. Un'anteprima sana: * risolve destinatario, modello, variabili del corpo, bottoni e header documento * rifiuta campioni JSON non validi * rifiuta target di mappatura non sicuri * rifiuta link a documenti non HTTPS * non invia un messaggio WhatsApp Quando la promozione verificata tramite run-log verrà rilasciata, le richieste dry-run firmate aggiungeranno run log lato server con `signatureValid: true`, stato `dry_run`, diagnostica della richiesta mappata sanificata, e nessuna archiviazione del payload cliente grezzo. ## Passo 4: passa agli invii live Finché la promozione live non viene rilasciata in Impostazioni/API, usa l'API diretta per gli invii in produzione: ```text theme={null} POST /api/v1/template-sends ``` Quando la promozione live verrà rilasciata, la checklist di promozione prevista sarà: 1. Almeno un dry-run firmato recente per la configurazione ha `signatureValid: true`. 2. Il dry-run ha risolto tutte le mappature richieste. 3. Il modello selezionato è ancora Utility approvato. 4. L'operatore ha accesso developer/admin. 5. Gli interruttori di emergenza a livello di configurazione e di area di lavoro consentono l'esecuzione. 6. I run log restano sanificati. ## Errori comuni nel rollout | Errore | Significato | Correzione | | ------------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | `missing_timestamp` | L'header della firma manca di `t=`. | Aggiungi il timestamp in secondi Unix a `X-Switchbord-Signature`. | | `expired_timestamp` | L'orologio del mittente è fuori dalla finestra di replay di cinque minuti. | Sincronizza l'orologio con NTP e firma immediatamente prima dell'invio. | | `invalid_signature` | Il digest non corrisponde al corpo grezzo. | Firma esattamente i byte del corpo grezzo della richiesta. | | `webhook_not_found_or_disabled` | La configurazione webhook creata da Impostazioni è ancora disabilitata. | Usa l'anteprima nel browser oggi; usa l'API diretta per gli invii in produzione finché la promozione non viene rilasciata. | | `invalid_mapping_target` | Il target di mappatura include un segmento di percorso vietato. | Rimuovi `__proto__`, `prototype` o `constructor` dalle chiavi di mappatura. | | `invalid_media_link` | L'URL del documento/immagine non è valido o non è HTTPS. | Usa un URL HTTPS pubblico. | | `template_not_approved_utility` | Il modello selezionato manca, è nascosto, non approvato o non è Utility. | Sincronizza/approva un modello Utility nell'area di lavoro. | ## Guide correlate * [Link alla ricevuta di pagamento tramite bottone URL](/it/guides/receipt-link-webhook) * [Ricevuta PDF tramite header DOCUMENT](/it/guides/pdf-receipt-webhook) * [Webhook in entrata](/it/api-reference/inbound-webhooks)