Documentation Index
Fetch the complete documentation index at: https://docs.zenoo.com/llms.txt
Use this file to discover all available pages before exploring further.
Go-Live Checklist
Complete every item before switching from staging to production. Each item addresses a specific failure mode observed in real integrations.Credentials and endpoints
1. Replace staging API key with production key
Update your environment configuration to use the production API key. Staging keys do not work against the production URL.2. Update base URL to production
Switch from the staging URL to the production URL. This must change everywhere your application makes Zenoo API calls.3. Update webhook endpoint to production URL
Point Zenoo at your production webhook endpoint. Contact your Zenoo account manager to update the webhook URL, or configure it in the Zenoo dashboard.Staging and production webhooks use different secrets. Update the secret in your configuration.
Security
4. Verify webhook signature validation works
Confirm that your webhook handler validates theX-Zenoo-Signature header on every request. Test by sending a webhook with a tampered payload and verifying that your handler rejects it.
Resilience
5. Implement exponential backoff retry logic
Your API client should retry 5xx errors and timeouts with increasing delays. Never retry 4xx errors without fixing the request.6. Set up idempotency with external_reference
external_reference is submitted twice, Zenoo returns the existing case.
Result handling
7. Handle all verdict outcomes
Your application must handle all threeoverall_verdict values. Verify your decision logic:
| Verdict | Required action |
|---|---|
Pass | Proceed with onboarding or approval |
Refer | Route to manual compliance review |
Fail | Block onboarding, escalate to compliance team |
8. Handle webhook edge cases
Your webhook handler must process all five event types, not justverification.completed:
| Event | Required action |
|---|---|
verification.completed | Process results, update customer record |
screening.completed | Review matches, update risk profile |
journey.abandoned | Send reminder or create a new journey |
journey.expired | Create a new verification journey |
check.failed | Alert compliance team for manual intervention |
9. Implement webhook deduplication
Zenoo may deliver the same webhook more than once. Your handler must be idempotent.200 for duplicates to prevent unnecessary retries.
Monitoring
10. Set up monitoring
Track these metrics from day one:| Metric | Alert threshold |
|---|---|
| API error rate (5xx) | > 5% over 10 minutes |
| Webhook delivery failures | > 3 consecutive failures |
| Average response time | > 30 seconds (sync mode) |
| Verification completion rate | < 90% over 1 hour |
| Sanctions hit rate | Sudden spike (> 2x normal) |
request_id from error responses to correlate application logs with Zenoo server logs.
11. Test one real verification in production
After completing items 1-10, run a single real verification in production. Use a real company or individual (not test data). Confirm:- API call succeeds with
200response - Response contains valid
overall_verdictandrisk_tier - Webhook is delivered to your production endpoint
- Webhook signature verifies correctly
- Your application processes the result correctly
12. Configure alerts for failures
Set up automated alerts for:- 5xx error spikes from the Zenoo API. These indicate server-side issues, contact Zenoo support.
- Webhook delivery failures. If your endpoint returns non-2xx for more than 3 consecutive webhooks, investigate immediately.
- Verification timeout increases. A sustained increase in response times may indicate provider degradation.
- Unusual verdict distributions. A sudden spike in
Failverdicts may indicate a configuration issue, not actual compliance failures.
Summary
Complete all 12 items before going live. Each item addresses a real production failure mode.
| # | Item | Status |
|---|---|---|
| 1 | Replace staging API key with production key | [ ] |
| 2 | Update base URL to production | [ ] |
| 3 | Update webhook endpoint to production URL | [ ] |
| 4 | Verify webhook signature validation works | [ ] |
| 5 | Implement exponential backoff retry logic | [ ] |
| 6 | Set up idempotency with external_reference | [ ] |
| 7 | Handle all verdict outcomes (Pass, Refer, Fail) | [ ] |
| 8 | Handle webhook edge cases (abandoned, expired, failed) | [ ] |
| 9 | Implement webhook deduplication | [ ] |
| 10 | Set up monitoring (error rates, webhooks, response times) | [ ] |
| 11 | Test one real verification in production | [ ] |
| 12 | Configure alerts for 5xx spikes and webhook failures | [ ] |
Next steps
- Error Handling — Retry strategies and circuit breaker behavior
- Webhooks Guide — Webhook event types and delivery
- Reference: Error Codes — Complete error code reference