Result Delivery

Zenoo supports three methods for delivering verification results. Choose based on your infrastructure, latency requirements, and integration complexity.

Pull via Token
Webhook Push
Ping + Pull

Pull via Token

The simplest approach. After initiating a verification, poll the pull endpoint until results are ready.How it works:

Initiate a verification (sync or async). Save the pull token from the response.
Poll GET /sharable-payload/{pull_token} at intervals.
When results are ready, the endpoint returns 200 with the full payload.

Polling Strategy

Time Window	Poll Interval	Rationale
0 to 2 minutes	Every 10 seconds	Most automated checks (screening, registry) complete in this window
2 to 10 minutes	Every 30 seconds	Allows for slower providers or queued checks
After 10 minutes	Stop polling	Switch to webhook or contact support

poll-results.js

async function pollResults(pullToken) {
  const maxAttempts = 30;

  for (let i = 0; i < maxAttempts; i++) {
    const response = await fetch(
      `https://instance.prod.onboardapp.io/api/gateway/sharable-payload/${pullToken}`
    );

    if (response.status === 200) return await response.json();
    if (response.status === 404) throw new Error("Token invalid or expired");

    // 204: still processing
    const delay = i < 12 ? 10_000 : 30_000;
    await new Promise((r) => setTimeout(r, delay));
  }

  throw new Error("Polling timeout. Results not ready after 10 minutes.");
}

Pull Endpoint Response Codes

Status	Meaning
`200`	Results are ready. Response body contains the full verification payload.
`204`	Still processing. Retry after a short delay.
`404`	Token is invalid or has expired.

Pull Token Lifetime

Pull tokens remain valid for 30 days after results become available. After that, the token expires and returns 404. Store results in your own system before the token expires.

Webhook Push

Zenoo pushes the full verification results to your endpoint as soon as they are ready. No polling needed.How it works:

Configure a webhook endpoint during onboarding.
Initiate a verification.
Zenoo POSTs the verification.completed event with full results to your endpoint.
Your endpoint returns 200 within 30 seconds.

This is the fastest delivery method. Results arrive the moment processing finishes, with no polling delay.Requirements:

HTTPS endpoint accessible from the internet.
Signature verification on every incoming webhook.
Response within 30 seconds.
Idempotent event handling (Zenoo may deliver the same event more than once).

See the Webhooks guide for full setup instructions.

Ping + Pull

A lightweight webhook notification tells you results are ready. You then fetch the full payload at your convenience.How it works:

Configure a webhook endpoint.
Initiate a verification.
Zenoo sends a small notification (status + pull token, no result data).
Your system fetches full results from the pull endpoint when ready.

This keeps webhook payloads small and decouples notification from data retrieval. Your system controls when and how it fetches results.Notification payload:

{
  "event_type": "verification.completed",
  "status": "complete",
  "callback_reference": "APP-2026-0123",
  "pull_token": "eyJhbGciOiJIUzI1NiJ9.pull-token...",
  "completed_at": "2026-01-15T14:35:00Z"
}

Then fetch results:

curl "https://instance.prod.onboardapp.io/api/gateway/sharable-payload/{pull_token}"

Comparison

Aspect	Pull via Token	Webhook Push	Ping + Pull
Mechanism	Poll endpoint at intervals	Full results pushed to your endpoint	Lightweight notification, you fetch results
Latency	Depends on poll interval (10-30s)	Near-instant	Near-instant notification, you control fetch timing
Complexity	Lowest	Medium (webhook endpoint + sig verification)	Medium (webhook + pull call)
Reliability	High (you control timing)	Depends on webhook delivery	High (notification + guaranteed pull)
Payload size	N/A (you fetch on demand)	Full results in webhook	Small notification, full results on pull
Best for	POC, low-volume, simple integrations	Real-time processing, event-driven architectures	Production systems, high-reliability requirements

Recommendation

For production, use Ping + Pull. You get real-time notification that results are available, with the flexibility to fetch full results on your own schedule. Small webhook payloads are more reliable to deliver, and you always have the pull endpoint as a fallback.

For POC and development: Use Pull via Token. It requires no webhook infrastructure. Just initiate a verification and poll for results. For event-driven architectures: Use Webhook Push. If your system is already built around event processing (message queues, serverless functions), receiving full results via webhook fits naturally.

Combining Methods

The most resilient pattern uses webhooks with polling as a fallback:

Configure webhooks for instant notification (push or ping+pull).
Implement a background job that polls for any verifications that have been pending longer than expected.
If a webhook is missed (endpoint down, network issue), the polling job catches it.

fallback-poller.js

// Background job: catch any missed webhooks
async function checkPendingVerifications() {
  const pending = await db.verifications.find({
    status: "pending",
    initiated_at: { $lt: new Date(Date.now() - 10 * 60 * 1000) } // >10 min ago
  });

  for (const v of pending) {
    const response = await fetch(
      `https://instance.prod.onboardapp.io/api/gateway/sharable-payload/${v.pull_token}`
    );
    if (response.status === 200) {
      const results = await response.json();
      await processResults(v.id, results);
    }
  }
}

Next Steps

Webhooks — Set up webhook endpoints and signature verification
Sync vs Async Flows — Choose between sync and async execution
Error Handling — Handle failures and timeouts during result retrieval

Getting Started

Use-Case Guides

Platform Concepts

Domain Concepts

Data Model

Result Delivery

Result Delivery

Pull via Token

Polling Strategy

Pull Endpoint Response Codes

Pull Token Lifetime

Webhook Push

Ping + Pull

Comparison

Recommendation

Combining Methods

Next Steps

​Result Delivery

​Pull via Token

​Polling Strategy

​Pull Endpoint Response Codes

​Pull Token Lifetime

​Webhook Push

​Ping + Pull

​Comparison

​Recommendation

​Combining Methods

​Next Steps

Result Delivery

Pull via Token

Polling Strategy

Pull Endpoint Response Codes

Pull Token Lifetime

Webhook Push

Ping + Pull

Comparison

Recommendation

Combining Methods

Next Steps