WazzAPIWazzAPI
Start Messaging
Pull Events

Event delivery for networks that cannot take webhooks

Pull is the outbound-HTTPS alternative to webhooks. Long-poll the same message and device events from behind NAT, a firewall, or a private network — no public callback URL required.

Read the Pull docs See API integration
Python create
from wazzapi import PullSubscriptionConsumer, WazzapiClient

with WazzapiClient(api_key="wz_live_••••••••") as client:
    created = client.pull_subscriptions.create(
        ["message.received", "device.connection_failed"],
        description="private CRM consumer",
    )
    token = created.token  # visible once — store it
Long-poll
GET /api/v1/pull/subscriptions/{id}/events?offset=210&limit=100&timeout=60
Authorization: Bearer wzpull_live_••••••••
X-Wazzapi-Poller-ID: stable-client-process-id
When to use it

Webhooks when you can. Pull when you cannot.

Keep webhooks as the default for public HTTPS endpoints. Switch to Pull when the consumer can only make outbound requests.

Pull is the right fit when
  • Your consumer sits behind NAT, a firewall, or a private network.
  • Local development and agent runtimes cannot expose a public webhook URL.
  • You want a durable cursor you control, with replay after crashes.
How it works

Long-poll with a durable cursor.

PostgreSQL stores the canonical events. Your poller acknowledges work by sending the last returned offset on the next request.

1

Create a subscription

Pick the same event types webhooks deliver. Store the Pull token immediately — plaintext is shown only on create and rotate.

2

Long-poll events

Your process makes outbound HTTPS requests. Long polling is near-real-time; short polls are for one-shot fetches.

3

Save the offset after work

Process the batch, deduplicate by event_id, then persist next_offset. A crash before save replays the batch.

Capabilities

Delivery you can recover from.

Pull and webhooks fan out independently. A stuck poller never blocks webhook customers, and a webhook retry never advances a Pull cursor.

Pull feature

Same events as webhooks

message.received, sent, delivered, read, failed, plus device.connected, disconnected, and connection_failed.

Pull feature

Outbound HTTPS only

No inbound ports. Pull is the delivery channel when you cannot receive callbacks.

Pull feature

Seven-day backlog

Replay from the last durable offset. Offsets older than retention return cursor_expired — no silent resync.

Pull feature

Official SDK consumers

Python and Node ship PullSubscriptionConsumer with durable offset stores and long-poll timeouts.

Start polling the same events as webhooks.

Create a Pull subscription, store the token, and run the official Python or Node consumer with a durable offset store.

Open Pull docs Start Messaging