Rollout dry-run dei webhook in entrata

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 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

Apri Impostazioni → Integrazioni → Webhook e API.
Clicca Crea webhook.
Seleziona un modello Utility approvato.
Mappa i campi richiesti.
Incolla un payload di esempio.
Clicca Esegui anteprima dry-run.
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.

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:

POST /api/v1/template-sends

Quando la promozione live verrà rilasciata, la checklist di promozione prevista sarà:

Almeno un dry-run firmato recente per la configurazione ha signatureValid: true.
Il dry-run ha risolto tutte le mappature richieste.
Il modello selezionato è ancora Utility approvato.
L’operatore ha accesso developer/admin.
Gli interruttori di emergenza a livello di configurazione e di area di lavoro consentono l’esecuzione.
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.

Per iniziare

Funzionalità

WhatsApp

Guide

Contribuire

Piattaforma

Operazioni

Sicurezza e Conformità

Rollout dry-run dei webhook in entrata

Comportamento attuale

Passo 1: crea il webhook

Passo 2: prepara le richieste firmate

Passo 3: ispeziona l’anteprima nel browser oggi

Passo 4: passa agli invii live

Errori comuni nel rollout

Guide correlate

​Comportamento attuale

​Passo 1: crea il webhook

​Passo 2: prepara le richieste firmate

​Passo 3: ispeziona l’anteprima nel browser oggi

​Passo 4: passa agli invii live

​Errori comuni nel rollout

​Guide correlate

Comportamento attuale

Passo 1: crea il webhook

Passo 2: prepara le richieste firmate

Passo 3: ispeziona l’anteprima nel browser oggi

Passo 4: passa agli invii live

Errori comuni nel rollout

Guide correlate