Sviluppatori

Inviare le risposte al tuo server con i webhook

Ricevi ogni risposta come payload JSON firmato e verifica che arrivi davvero da StrawPoll.

Ultimo aggiornamento

Un webhook invia ogni risposta a un indirizzo del tuo server, come richiesta POST con un corpo JSON.

Configurarlo

  1. Apri Integrazioni nella tua dashboard, fai clic su Aggiungi un’integrazione e scegli Webhooks.
  2. Inserisci l’URL del tuo endpoint. Deve iniziare con https:// ed essere raggiungibile da Internet.
  3. Facoltativo: aggiungi gli header che il tuo endpoint si aspetta, ad esempio un header Authorization.
  4. Scegli il sondaggio e se inviare le risposte nuove, quelle modificate o entrambe, poi salva.
  5. Copia il Secret di firma dalla pagina dell’integrazione, poi fai clic su Invia prova.

Il payload

json
{
	"id": "0193f1c2-…",
	"event": "response.created",
	"createdAt": "2026-11-08T14:05:12.000Z",
	"form": {
		"id": "…",
		"slug": "pranzo-team",
		"name": "Pranzo del team",
		"title": "Dove mangiamo venerdì?",
		"url": "https://strawpoll.com/…"
	},
	"response": {
		"id": "…",
		"createdAt": "2026-11-08T14:05:11.000Z",
		"updatedAt": null,
		"deletedAt": null,
		"respondent": { "name": "Sam", "email": "sam@example.com", "phone": null },
		"answers": [
			{
				"fieldId": "…",
				"question": "D1 · Dove mangiamo?",
				"value": "…",
				"text": "Pizza"
			}
		],
		"comment": null
	}
}
  • event vale response.created, response.updated, response.deleted oppure ping per Invia prova.
  • Con response.deleted, deletedAt indica quando il partecipante ha eliminato la sua risposta e answers contiene quello che aveva inviato. Eliminala anche dai tuoi dati.
  • id è univoco per ogni consegna. Usalo per ignorare una consegna che hai già elaborato.
  • answers elenca tutte le domande, in ordine. text è la risposta così come appare nei tuoi risultati; value è il valore grezzo, la cui forma dipende dal tipo di domanda.
HeaderContenuto
X-StrawPoll-EventL’evento, ad esempio response.created
X-StrawPoll-DeliveryL’id della consegna
X-StrawPoll-TimestampIl momento dell’invio, in secondi Unix
X-StrawPoll-Signaturesha256= seguito dalla firma

Verificare la firma

La firma è un HMAC-SHA256, calcolato con il tuo segreto di firma, dell’ID della consegna, del timestamp e del corpo grezzo della richiesta, uniti da punti. Calcolala tu stesso e confrontala:

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

function isFromStrawPoll(request, rawBody, secret) {
	const id = request.headers['x-strawpoll-delivery'];
	const timestamp = request.headers['x-strawpoll-timestamp'];
	const signature = request.headers['x-strawpoll-signature'] ?? '';

	const expected =
		'sha256=' + createHmac('sha256', secret).update(`${id}.${timestamp}.${rawBody}`).digest('hex');
	const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) < 300;

	return (
		fresh &&
		signature.length === expected.length &&
		timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
	);
}

Firma il corpo esattamente come è arrivato, prima di analizzarlo. Rifiutare i timestamp troppo vecchi impedisce a qualcuno di ripetere una richiesta intercettata.

Se il tuo segreto potrebbe essere trapelato, fai clic su Rigenera nella pagina dell’integrazione. Il vecchio segreto smette subito di funzionare, quindi aggiorna il tuo endpoint.

Rispondere in tempo

Rispondi con un qualsiasi stato 2xx entro 10 secondi. Esegui le operazioni lente dopo aver risposto.

Se una consegna non va a buon fine, StrawPoll la ritenta tre volte nel mezzo minuto successivo, con lo stesso id. Non ritenta dopo una risposta 4xx diversa da 429 e non segue mai i reindirizzamenti. Ogni tentativo compare in Invii recenti, con la risposta del tuo server.