Webhooks vs Polling vs SSE: Choosing the Right Approach for Async Parsing Results

When you send a large document to PeterParser for async processing, you need to know when it's done. We offer three approaches, each with different trade-offs.

1. Webhooks — Push to Your Server

Provide a webhook_url when submitting a job. PeterParser POSTs the result when done, signed with HMAC-SHA256 via your per-key webhook_secret. Three retries with exponential backoff.

curl -X POST https://api.peterparser.com/v2/documents \
  -H "X-API-Key: pp_live_..." \
  -d '{
    "url": "https://example.com/report.pdf",
    "mode": "async",
    "webhook_url": "https://yourapp.com/api/callback"
  }'

2. Polling — Check When You Want

Submit a job, get a job_id, poll GET /v2/documents/jobs/{job_id} until done. Start at 3-second intervals, back off to 10 seconds.

3. SSE Events — Real-Time Stream

Open one persistent HTTP connection and receive events for ALL your jobs in real-time. Auto-closes after the TTL you set (default 5 min, max 1 hour).

curl -N -H "X-API-Key: pp_live_..." \
  "https://api.peterparser.ai/v2/events?ttl=600"

Missed events? GET /v2/events/history returns the last 100 events (retained 10 minutes).

Comparison

All three work simultaneously. Use SSE for your dashboard, webhooks for your backend pipeline, and polling for one-off scripts.