Webhook (JSON)

Una regola Webhook invia in POST ogni risposta corrispondente come JSON a un URL che indichi tu. Usala per alimentare un CRM, uno strumento di fogli di calcolo, il tuo server o una piattaforma di automazione come Zapier, Make o n8n.

Creare una regola webhook

1. Fai clic su + Nuova regola e scegli Webhook
2. Quando: lascia Ogni risposta, oppure scegli Solo dopo l'approvazione / Quando viene rifiutata e imposta un approvatore. Aggiungi condizioni Solo se per inviare solo le risposte corrispondenti
3. Destinatario: incolla l'URL del tuo endpoint (solo HTTPS). Non c'è un passaggio Messaggio: la regola invia un payload JSON fisso. Mostra payload, sotto l'URL, lo mostra con le domande del tuo modulo, pronto da copiare
4. Fai clic su Crea regola, poi copia il segreto di firma mostrato una sola volta (vedi sotto)

Invia test manda un payload di esempio firmato all'endpoint e mostra lo stato HTTP restituito. Gli URL salvati vengono conservati cifrati e mostrati mascherati; fai clic su Sostituisci per incollarne uno nuovo.

Il payload

Ogni richiesta è un POST, Content-Type: application/json, con questo corpo:

{
  "version": 1,
  "event": "submitted",
  "form": { "id": "1AbC...", "name": "Workshop sign-up" },
  "response": {
    "id": "a3f1...",
    "submittedAt": "2026-01-31T09:30:00.000Z",
    "respondentEmail": "respondent@example.com",
    "answers": [
      { "questionId": "q1", "title": "Your name", "value": "Ada Lovelace" },
      { "questionId": "q3", "title": "Department", "value": "Ops" }
    ]
  },
  "rule": { "id": "rule id", "name": "Zapier: new lead" }
}

• event è uno tra submitted, approved, rejected; viaggia anche nell'header X-Skyfield-Event
• response.respondentEmail è null a meno che il modulo non raccolga gli indirizzi email
• answers[].value è sempre una stringa; le risposte con caselle di controllo sono unite con ,
• rule.id e rule.name identificano la regola che si è attivata; name è null se la regola non ha un nome
• Su approved e rejected viene incluso in più approval: { "decision": "approved", "decidedBy": "Dana" }. decidedBy è il nome che l'approvatore ha digitato nella pagina di approvazione, altrimenti l'email dell'approvatore, oppure null

version resta 1 finché la struttura sopra è stabile. Possono essere aggiunti nuovi campi; nessuno viene rimosso o rinominato senza un cambio di versione.

Verificare la firma

Ogni richiesta porta un header X-Skyfield-Signature: sha256=<hex>, l'HMAC-SHA256 del corpo grezzo della richiesta con il segreto di firma della tua regola come chiave. Verificalo prima di fidarti di una richiesta.

Il segreto (whsec_...) viene mostrato una sola volta, subito dopo il salvataggio che assegna alla regola il suo primo URL di webhook. Copialo in quel momento; non può essere mostrato di nuovo. Sostituire l'URL in seguito mantiene lo stesso segreto. Se lo perdi, apri la regola, fai clic su Nuovo segreto di firma e salva: il nuovo segreto viene mostrato una volta e il vecchio smette subito di funzionare.

Calcola l'HMAC sui byte del corpo esattamente come ricevuti. Se prima analizzi e riserializzi il JSON, gli spazi cambiano e il confronto fallisce.

Node.js

import { createHmac, timingSafeEqual } from 'node:crypto'

// rawBody: string or Buffer of the request body, before any JSON parsing
function verify(rawBody, header, secret) {
  const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex')
  const a = Buffer.from(expected)
  const b = Buffer.from(header ?? '')
  return a.length === b.length && timingSafeEqual(a, b)
}

// Express example: use express.raw() so req.body is the untouched bytes
app.post('/hook', express.raw({ type: 'application/json' }), (req, res) => {
  if (!verify(req.body, req.get('X-Skyfield-Signature'), process.env.SKYFIELD_SECRET))
    return res.status(401).end()
  const payload = JSON.parse(req.body)
  res.status(200).end()
})

Python

import hmac, hashlib

def verify(raw_body: bytes, header: str, secret: str) -> bool:
    digest = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest("sha256=" + digest, header or "")

# Flask example
@app.post("/hook")
def hook():
    if not verify(request.get_data(), request.headers.get("X-Skyfield-Signature"), SECRET):
        return "", 401
    payload = request.get_json()
    return "", 200

Rispondi con qualsiasi stato 2xx. Il corpo viene ignorato.

Zapier, Make, n8n

Tutti e tre accettano un webhook JSON generico:

• Zapier: trigger Webhooks by Zapier, evento Catch Hook (oppure Catch Raw Hook per verificare la firma tu stesso). Incolla nella regola l'URL mostrato da Zapier
• Make: aggiungi un modulo Webhooks, Custom webhook, e copia il suo URL
• n8n: aggiungi un nodo Webhook, metodo POST, e usa il suo URL di produzione

Invia un test dalla regola, poi mappa i campi di response.answers nella piattaforma. Il payload di esempio usa risposte fittizie, così ogni campo è presente.

Consegna e limiti

• L'endpoint deve essere raggiungibile sull'internet pubblica via HTTPS. Gli indirizzi privati e locali vengono rifiutati al salvataggio
• I reindirizzamenti non vengono seguiti: usa l'URL finale
• L'endpoint ha 5 secondi per rispondere. Un timeout o una risposta 5xx viene ritentata una volta
• Una risposta 404 o 410 significa che l'endpoint non esiste più: la regola viene messa in pausa e ricevi una sola email. Incolla un nuovo URL sulla regola per riprendere
• La pagina Cronologia elenca ogni consegna con lo stato HTTP restituito dal tuo endpoint
• Una regola webhook in pausa o disattivata non blocca le altre regole del modulo

Buono a sapersi

• Una regola webhook rispetta Invia quando, quindi un endpoint può ricevere una decisione di approvazione invece di ogni invio. Vedi Invia quando
• Per inviare solo risposte verificate, imposta Invia quando della regola su Solo dopo l'approvazione e scegli un approvatore. Vedi Approvazione. Il payload contiene allora approval.decision
• Cambia canale… sposta una regola webhook su Email o su un canale di chat; indica lì la nuova destinazione. Se torni al webhook, l'URL va incollato di nuovo
• Le regole webhook richiedono una licenza attiva. La prova gratuita conta. Vedi cosa richiede una licenza