Endpoints de polling

Un endpoint de polling vous fournit le même flux d’événements qu’un endpoint webhook, mais vous les récupérez avec une requête GET au lieu que storekit ne les pousse vers une URL publique. Chaque requête de polling renvoie un lot de messages dans l’ordre où ils ont été reçus ; vous traitez le lot, validez la position atteinte, et la requête suivante reprend à partir de là.

Quand utiliser le polling

Le polling convient aux cas où un endpoint HTTPS public est peu pratique ou inutile :

Développement local, interrogez depuis votre ordinateur portable sans ngrok ni tunnel
Réseaux privés, le service consommateur ne doit pas être accessible depuis Internet
Traitement par lots, vous voulez tous les événements de la journée en une seule fois, par exemple pour archiver les commandes à des fins de conformité ou pour rapprocher les paiements durant la nuit
Systèmes qui ne peuvent pas recevoir de HTTP, une tâche cron, un pipeline de données ou un script

Si vous avez besoin des événements en quelques secondes après leur survenue, utilisez un endpoint webhook classique. Les endpoints de polling et les endpoints webhook peuvent coexister sur le même compte, filtrés sur les mêmes types d’événements ou sur des types différents.

Créer un endpoint de polling

Ouvrez la page des webhooks (Settings → Developers → Manage Webhooks)
Dans le portail webhooks intégré, ajoutez un nouvel endpoint et choisissez le type d’endpoint de polling
Sélectionnez les types d’événements que vous souhaitez recevoir
Enregistrez l’endpoint

Le portail affiche alors deux éléments dont vous avez besoin pour chaque requête :

Valeur	Exemple	Description
URL de polling	`https://api.svix.com/api/v1/app/app_xxx/polling-endpoint/poll_xxx/consumer/{consumer_id}`	Unique à cet endpoint. Copiez-la exactement telle qu’affichée (l’hôte dépend de la région) et remplacez `{consumer_id}` par votre propre identifiant
Clé API	`sk_poll_*****`	Envoyée en tant que Bearer token. Affichée une seule fois, conservez-la de manière sécurisée

La clé API accorde un accès en lecture à tous les événements auxquels l’endpoint est abonné, y compris les noms des clients et les coordonnées de contact dans les payloads de commandes. Traitez-la comme n’importe quel autre secret de production.

Interroger les événements

Envoyez une requête GET à l’URL de polling avec votre clé API :

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 réponse est un lot de messages. Le payload de chaque message correspond exactement au corps JSON qu’un endpoint webhook recevrait, l’enveloppe { event, data } du format de payload, enrichi de métadonnées de message et d’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
}

Champ	Description
`data`	Messages dans l’ordre où ils ont été reçus. Vide lorsqu’il n’y a rien de nouveau
`data[].payload`	Le corps du webhook : `payload.event` nomme l’événement, `payload.data` contient les données de l’événement
`data[].offset`	Position du message dans le flux. Validez cette valeur une fois le message traité
`done`	`true` lorsque ce lot a atteint la fin du flux ; `false` signifie qu’il faut à nouveau interroger immédiatement pour obtenir la suite

La vérification de signature ne s’applique pas, la requête est authentifiée par votre clé API plutôt que par une livraison signée.

Valider votre position

Après avoir traité un lot, validez l’offset du dernier message que vous avez traité :

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

Tant que vous ne validez pas, les mêmes messages sont redistribués une fois leur bail expiré. C’est délibéré : si votre worker plante en plein milieu d’un lot, rien n’est perdu. Cela signifie aussi que votre gestionnaire doit être idempotent, voir Idempotence.

IDs de consommateur

Le {consumer_id} dans l’URL est une chaîne que vous choisissez. Chaque ID de consommateur suit sa propre position dans le flux, ainsi deux consommateurs qui lisent le même endpoint reçoivent chacun tous les événements.

Utilisez un ID stable par worker (kitchen-archive, finance-reconciliation) pour que la progression survive aux redémarrages
Ne partagez jamais un même ID de consommateur entre plusieurs clients qui s’exécutent en même temps. Deux processus qui interrogent avec le même ID de consommateur se désynchronisent dans le flux et l’API renvoie des erreurs

Le flux démarre au moment où l’endpoint de polling est créé. Les événements envoyés avant cela ne sont pas inclus.

Une boucle de polling typique

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

Exécutez pollOnce() selon le rythme qui vous convient, toutes les quelques secondes pour du quasi temps réel, ou une fois par nuit pour un export quotidien.

Transférer vers un service privé

Si vous préférez conserver une livraison HTTP de type webhook mais que votre service se trouve sur un réseau privé, exécutez Svix Bridge à l’intérieur de ce réseau. Il interroge l’endpoint et transfère chaque message vers une URL interne, RabbitMQ ou Kafka, avec des nouvelles tentatives lorsque l’un ou l’autre côté est temporairement inaccessible. La page de l’endpoint de polling dans le portail intégré inclut une configuration Bridge de démarrage avec l’ID d’application et l’ID d’endpoint pré-remplis.

Ressources associées

Configurer les webhooks

Livraison push vers un endpoint HTTPS public

Idempotence

Gérer sans risque plusieurs livraisons du même événement

Événements webhook

Tous les types d’événements auxquels vous pouvez vous abonner

Tester les webhooks

Inspectez les livraisons et envoyez des événements de test

Developers

Guides

Ordering Agents

Merchant MCP

Webhooks

Endpoints de polling

Quand utiliser le polling

Créer un endpoint de polling

Interroger les événements

Valider votre position

IDs de consommateur

Une boucle de polling typique

Transférer vers un service privé

Ressources associées

Configurer les webhooks

Idempotence

Événements webhook

Tester les webhooks

​Quand utiliser le polling

​Créer un endpoint de polling

​Interroger les événements

​Valider votre position

​IDs de consommateur

​Une boucle de polling typique

​Transférer vers un service privé

​Ressources associées

Configurer les webhooks

Idempotence

Événements webhook

Tester les webhooks

Quand utiliser le polling

Créer un endpoint de polling

Interroger les événements

Valider votre position

IDs de consommateur

Une boucle de polling typique

Transférer vers un service privé

Ressources associées