Webhooks for API products
When to prefer webhooks over polling, how to verify deliveries, and a production-ready receiver checklist.
Practical how-to articles published by APISeeker. Providers do not publish marketplace guides.
When webhooks beat polling
Polling works for infrequent checks, but it wastes quota and adds lag when events are rare. Webhooks invert the model: the provider POSTs to your HTTPS endpoint when something changes.
Prefer webhooks for job completion (OCR finished), status transitions (flight delayed), billing events, and anything where “near real time” matters more than a fixed poll interval.
Keep a light poll as a fallback only if the provider documents missed deliveries or if you need reconciliation after downtime.
Design a solid receiver endpoint
Expose a dedicated HTTPS URL (for example /webhooks/apiseeker/invoice-ocr). Do not reuse a generic form endpoint.
Accept POST with JSON. Reject unknown content types early. Return 2xx only after you have accepted the payload for processing — ideally after writing it to a queue or durable store.
Keep the HTTP handler short: verify → persist → ack. Heavy work (OCR result import, emails, DB joins) belongs in a worker.
// Express-style sketch — verify, enqueue, ack
app.post("/webhooks/invoice-ocr", express.raw({ type: "application/json" }), async (req, res) => {
const signature = req.get("X-Webhook-Signature") || "";
if (!verifyHmac(req.body, signature, process.env.WEBHOOK_SECRET)) {
return res.status(401).json({ error: "invalid_signature" });
}
const event = JSON.parse(req.body.toString("utf8"));
await queue.add("webhook", { id: event.id, type: event.type, data: event.data });
return res.status(202).json({ accepted: true });
});Verify signatures before you trust the body
Anyone who discovers your URL can POST fake events. Treat unsigned or invalid signatures as hostile.
Typical pattern: HMAC-SHA256 over the raw body with a shared secret, sent in a header. Compare using a constant-time equality check.
Rotate secrets carefully: accept both old and new secrets for a short window, then revoke the old one.
Make handlers idempotent
Providers retry on timeouts and 5xx. You will see the same event more than once.
Use the provider’s event id (or a hash of type + resource id + timestamp) as a unique key. Skip work you already completed.
Store processing state: received → processing → done / failed. That makes retries and support investigations much easier.
Retries, timeouts and dead letters
Return 2xx quickly (often under a few seconds). If you take too long, the sender may retry while you are still working — doubling load.
On your side, retry outbound side effects with backoff. Move permanently failing events to a dead-letter queue for human review.
Log the event id, delivery attempt and outcome without dumping full PII payloads into shared logs.
Security checklist
HTTPS only. Reject cleartext callbacks.
Keep the webhook secret in a secrets manager — never in the frontend or a public repo.
Optional hardening: IP allowlists when the provider publishes static egress, and timestamp / replay windows so old signed payloads cannot be reused forever.
Separate staging and production secrets and callback URLs.
How to test without guessing
Use the provider’s “send test event” if available. Otherwise replay a captured signed payload in staging with the staging secret.
Simulate duplicate deliveries and out-of-order events. Confirm your idempotency keys hold.
Chaos-test your queue: what happens if the worker is down for 10 minutes? Can you drain safely when it returns?
How this maps on APISeeker
Many marketplace APIs still start with request/response + polling for async jobs (for example invoice OCR job status). Build your client behind a small “event adapter” so you can plug a webhook later.
When an API documents async job completion, prefer that flow over tight polling loops, and always honor published rate limits.
Explore related listings, try the playground, then wire production keys from your dashboard.
Key takeaways
- Prefer webhooks for rare, latency-sensitive events; keep a light poll only as backup.
- Verify HMAC (or equivalent) on the raw body before parsing business logic.
- Ack fast with 2xx, process asynchronously, and de-dupe by event id.
- Plan for retries, secret rotation and dead-letter handling before go-live.
Keep learning
- GuideAPI pagination patternsCursor vs offset pagination — and how to avoid missing or duplicate rows.
- GuideAPI error handlingMap HTTP status codes to client behavior without leaking secrets.
- GuideAPI observability basicsWhat to measure so incidents are diagnosable before customers complain.
- GuideAPI security basicsProtect keys, validate inputs and assume every network path can be hostile.
Ready to integrate?
Compare plans, open docs, and try endpoints in the playground — then create a key when you are ready for production traffic.