Endpoint di polling

Un endpoint di polling fornisce lo stesso flusso di eventi di un endpoint webhook, ma li recuperi tu con una richiesta GET invece che storekit li invii a un URL pubblico. Ogni polling restituisce un batch di messaggi nell’ordine in cui sono stati ricevuti; elabori il batch, confermi il punto in cui sei arrivato e il polling successivo continua da lì.

Quando usare il polling

Il polling è adatto ai casi in cui un endpoint HTTPS pubblico è scomodo o non necessario:

Sviluppo locale: esegui il polling dal tuo laptop senza ngrok o un tunnel
Reti private: il servizio consumatore non deve essere raggiungibile da internet
Elaborazione in batch: vuoi tutti gli eventi della giornata in una volta sola, ad esempio per archiviare gli ordini per motivi di conformità o per riconciliare i pagamenti durante la notte
Sistemi che non possono ricevere HTTP: un cron job, una pipeline di dati o uno script

Se hai bisogno degli eventi entro pochi secondi dal loro verificarsi, usa un normale endpoint webhook. Gli endpoint di polling e webhook possono coesistere sullo stesso account, filtrati sugli stessi tipi di evento o su tipi diversi.

Creare un endpoint di polling

Apri la pagina dei webhook (Settings → Developers → Manage Webhooks)
Nel portale webhook integrato, aggiungi un nuovo endpoint e scegli il tipo endpoint di polling
Seleziona i tipi di evento che vuoi ricevere
Salva l’endpoint

Il portale mostra quindi due elementi che ti servono per ogni richiesta:

Valore	Esempio	Descrizione
URL di polling	`https://api.svix.com/api/v1/app/app_xxx/polling-endpoint/poll_xxx/consumer/{consumer_id}`	Unico per questo endpoint. Copialo esattamente come mostrato (l’host dipende dalla regione) e sostituisci `{consumer_id}` con il tuo identificatore
API key	`sk_poll_*****`	Inviata come Bearer token. Mostrata una sola volta, conservala in modo sicuro

La API key concede l’accesso in lettura a ogni evento a cui l’endpoint è sottoscritto, inclusi nomi dei clienti e dettagli di contatto nei payload degli ordini. Trattala come qualsiasi altro segreto di produzione.

Polling degli eventi

Invia una richiesta GET all’URL di polling con la tua API key:

curl -X GET "https://api.svix.com/api/v1/app/app_xxx/polling-endpoint/poll_xxx/consumer/kitchen-archive" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer sk_poll_*****"

La risposta è un batch di messaggi. Il payload di ogni messaggio è esattamente il corpo JSON che riceverebbe un endpoint webhook (l’envelope { event, data } del formato del payload), incapsulato con metadati del messaggio e un offset:

{
  "data": [
    {
      "id": "msg_2K2N9Qk...",
      "eventType": "order.created",
      "payload": {
        "event": "order.created",
        "data": {
          "id": 123456,
          "status": "created",
          "venue": { "id": 789, "name": "Pizza Palace" },
          "total": 2450
        }
      },
      "timestamp": "2025-01-17T12:00:00.000Z",
      "offset": 0
    }
  ],
  "done": true
}

Campo	Descrizione
`data`	Messaggi nell’ordine in cui sono stati ricevuti. Vuoto quando non c’è nulla di nuovo
`data[].payload`	Il corpo del webhook: `payload.event` indica il nome dell’evento, `payload.data` contiene i dati dell’evento
`data[].offset`	Posizione del messaggio nello stream. Conferma questo valore una volta elaborato
`done`	`true` quando questo batch ha raggiunto la fine dello stream; `false` significa che occorre eseguire subito un nuovo polling per ottenere altri messaggi

La verifica della firma non si applica: la richiesta è autenticata dalla tua API key anziché da una consegna firmata.

Confermare la tua posizione

Dopo aver elaborato un batch, conferma l’offset dell’ultimo messaggio gestito:

curl -X POST "https://api.svix.com/api/v1/app/app_xxx/polling-endpoint/poll_xxx/consumer/kitchen-archive/commit" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk_poll_*****" \
  -d '{ "offset": 0 }'

Finché non confermi, gli stessi messaggi vengono riconsegnati una volta scaduto il loro lease. Questo è voluto: se il tuo worker va in crash a metà batch, nulla va perso. Significa anche che il tuo handler deve essere idempotente, vedi Idempotenza.

ID dei consumer

Il {consumer_id} nell’URL è una stringa che scegli tu. Ogni ID consumer tiene traccia della propria posizione nello stream, quindi due consumer che leggono lo stesso endpoint ricevono entrambi ogni evento.

Usa un ID stabile per worker (kitchen-archive, finance-reconciliation) in modo che il progresso sopravviva ai riavvii
Non condividere mai un singolo ID consumer tra client eseguiti in parallelo. Due processi che effettuano polling con lo stesso consumer si disallineano nello stream e l’API restituisce errori

Lo stream inizia quando viene creato l’endpoint di polling. Gli eventi inviati prima di quel momento non sono inclusi.

Un tipico loop di polling

const URL = process.env.STOREKIT_POLL_URL;   // includes your consumer id
const KEY = process.env.STOREKIT_POLL_KEY;

async function pollOnce() {
  let done = false;
  while (!done) {
    const res = await fetch(URL, {
      headers: { Accept: 'application/json', Authorization: `Bearer ${KEY}` },
    });
    const body = await res.json();

    for (const msg of body.data) {
      await handleEvent(msg.payload.event, msg.payload.data);
    }

    if (body.data.length > 0) {
      const last = body.data[body.data.length - 1];
      const commit = await fetch(`${URL}/commit`, {
        method: 'POST',
        headers: {
          Accept: 'application/json',
          'Content-Type': 'application/json',
          Authorization: `Bearer ${KEY}`,
        },
        body: JSON.stringify({ offset: last.offset }),
      });
      if (!commit.ok) throw new Error(`Commit failed: ${commit.status}`);
    }

    done = body.done;
  }
}

Esegui pollOnce() con la pianificazione più adatta: ogni pochi secondi per un funzionamento quasi in tempo reale, oppure una volta a notte per un’esportazione giornaliera.

Inoltro a un servizio privato

Se preferisci mantenere la consegna HTTP in stile webhook ma il tuo servizio si trova su una rete privata, esegui Svix Bridge all’interno di quella rete. Effettua il polling dell’endpoint e inoltra ciascun messaggio a un URL interno, RabbitMQ o Kafka, con nuovi tentativi quando una delle due parti è temporaneamente non raggiungibile. La pagina dell’endpoint di polling nel portale integrato include una configurazione iniziale di Bridge con l’app ID e l’endpoint ID già compilati.

Correlati

Configurazione dei webhook

Consegna push a un endpoint HTTPS pubblico

Idempotenza

Gestisci lo stesso evento più volte in modo sicuro

Eventi webhook

Tutti i tipi di evento a cui puoi sottoscriverti

Test dei webhook

Ispeziona le consegne e invia eventi di test

Developers

Guides

Ordering Agents

Merchant MCP

Webhooks

Endpoint di polling

Quando usare il polling

Creare un endpoint di polling

Polling degli eventi

Confermare la tua posizione

ID dei consumer

Un tipico loop di polling

Inoltro a un servizio privato

Correlati

Configurazione dei webhook

Idempotenza

Eventi webhook

Test dei webhook

​Quando usare il polling

​Creare un endpoint di polling

​Polling degli eventi

​Confermare la tua posizione

​ID dei consumer

​Un tipico loop di polling

​Inoltro a un servizio privato

​Correlati

Configurazione dei webhook

Idempotenza

Eventi webhook

Test dei webhook

Quando usare il polling

Creare un endpoint di polling

Polling degli eventi

Confermare la tua posizione

ID dei consumer

Un tipico loop di polling

Inoltro a un servizio privato

Correlati