Polling Endpoints

Polling Endpoints are a way for your users to get a stream of events by polling instead of listening to webhooks.

When is polling better?

There are a few examples where polling for events works better than webhooks.

One example is when testing webhooks locally. It’s much easier to poll for events than exposing a public HTTP endpoint (even with tools like Svix Play or ngrok).

Another example is when your users don’t care about getting events in real-time and prefer getting them all at once at the end of a day. One place where this use-case comes up, is when your users need to store all events for compliance reasons. In that case batching and saving them all at once is easier and more cost efficient for them.

Enabling Polling Endpoints

Polling Endpoints can be enabled at the environment level in the Svix Dashboard  by enabling Advanced Endpoint Types.

When you enable Polling Endpoints, your users will be able to create them in the App Portal.

Usage

Like with webhook endpoints, Polling Endpoints support filtering messages by event types and channels.

In the App Portal, consumers will get a unique URL and an API key to iterate through the full list of events sent to their Svix Application since the endpoint was created.

When creating a Polling Endpoint, consumers will get a unique URL like https://api.us.svix.com/api/v1/app/app_2mG6DgUaGlwCNdM5oRCUJec2kQC/polling-endpoint/poll_59q/consumer/{consumer_id}

This URL can be polled to receive messages for a given Consumer ID. Each consumer tracks its own progress independently.

curl \
  -X GET "https://api.us.svix.com/api/v1/app/app_2mG6DgUaGlwCNdM5oRCUJec2kQC/polling-endpoint/poll_59q/consumer/MY_CONSUMER_ID" \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer sk_poll_*****.eu'

Each message includes an offset. Messages are returned in the order they were received.

{
  "data": [{
    "id": "msg_2K2N9Qk...",
    "eventType": "invoice.created",
    "payload": { "hello": "world" },
    "timestamp": "2025-01-17T00:00:00.000Z",
    "offset": 0
  }],
  "done": true
}

After processing a batch, commit the last message’s offset so the next poll continues from there.

curl \
  -X POST "https://api.us.svix.com/api/v1/app/app_2mG6DgUaGlwCNdM5oRCUJec2kQC/polling-endpoint/poll_59q/consumer/MY_CONSUMER_ID/commit" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer sk_poll_*****.eu' \
  -d '{ "offset": 0 }'

Until you commit, the same messages may be returned again after the lease expires. Use a stable Consumer ID per worker so progress is preserved across restarts.

Consumer IDs are arbitrary strings used by a client to self-identify.

Note that Consumer IDs should be unique per client and should not be shared. Put another way, Consumer IDs track exclusive sequential access through the stream of messages. Shared concurrent access through a given Consumer ID will result in errors as mutual clients drift in their positions in the stream.

Usage with Svix Bridge

If you have a service that must not be exposed on the public internet and you want it to receive webhooks from Svix, you can deploy a Svix Bridge  instance inside the same network that forwards messages from a polling endpoint to the destination service. Svix Bridge will take care of retrying in case the connection the Svix API or the destination service is temporarily lost.

The app portal page for the Polling Endpoint includes a basic example config for Svix Bridge, with the app ID and sink ID already filled in. It looks like this:

receivers:
  - name: "msg-poller-to-http"
    input:
      type: "svix-message-poller"
      consumer_id: "svix-bridge-1"
      app_id: "app_xxxxxxxxxxxxxxxxxxxxxxxxxxx"
      sink_id: "poll_yyy"
      token: "sk_poll_*****.eu"
    output:
      type: "http"
      url: "http://example.local"

The http output is not the only destination Svix Bridge can send webhooks to, it can also store them to a messaging system like RabbitMQ or Kafka. Further, you can set a transformation - a small JS program that processes each message before it gets forwarded.

For the full list of supported configuration options and how to configure each of the output types, see the receivers example config file .

Polling Endpoints can be used in parallel with regular Svix webhooks, and you don’t need to make any changes to how you create messages.