Skip to main content
Before routing real traffic to your integration, go through this checklist. Each item represents a class of problem we have seen in deployments — better to fix it beforehand than to chase it down later.

​
Authentication and secrets

No hardcoded keys in the code. Verify with:
git grep "tly_live_" --  # should return empty
Use a secrets manager (Doppler, AWS Secrets Manager, HashiCorp Vault, Vercel env vars) instead of a committed .env file.
Review each API key and remove unnecessary scopes. A service that only sends messages does not need agents:write or contacts:write.
Confirm that the handler validates the X-Timely-Signature header before processing any event. Test with a tampered payload — it should return 401.
Set a rotation date (suggestion: every 90 days) and document the internal procedure. See the step-by-step in Authentication → Rotating a key.

​
API and integration

Confirm the code points to https://api.timelyai.com.br/v1 and that the x-api-key belongs to the production workspace — not a test workspace. In CI/CD, use separate environment variables per stage.
Every API call has retry logic that respects the Retry-After header when receiving 429. Without this, load spikes can cause cascading errors.
If you fetch lists (conversations, contacts, agents), the code iterates over all pages using meta.total_pages. Fetching only page 1 may omit records.
Configure a timeout of at least 15 seconds for API calls. Requests without a timeout will stall workers indefinitely in case of network slowness.

​
Webhooks

Confirm the webhook URL is accessible from the internet (not localhost). Test with:
curl -X POST https://yoursite.com/webhook/timely \
  -H "Content-Type: application/json" \
  -d '{"test": true}'
The handler responds immediately and processes the event asynchronously (queue, worker). Synchronous processing that takes more than 10 seconds causes unnecessary retries.
The handler uses X-Timely-Event-Id to deduplicate events delivered more than once during retries.
Failed webhook events are available in the dashboard under Settings → Webhooks → [endpoint] → Event log. Set up an internal alert if the failure rate rises above 1%.

​
Agents and channels

Run the test chat with at least 20 variations of questions your customers would ask. Include out-of-scope questions — verify the agent responds politely without hallucinating.
Define the handoff rule (keyword, intent, number of turns without resolution). Confirm a human attendant receives the notification correctly.
Send a message from a real number to the production channel and follow the full flow: receipt → agent processing → response → conversation log in the CRM.
If you use proactive sending (outside the 24-hour window), templates must be approved by Meta before go-live. Approval can take 24 hours to 7 days.

​
Monitoring and alerts

Assign a team member to monitor the dashboard during the first 48 hours after go-live. Catch issues before they become customer complaints.
Under Settings → Billing → Alerts, enable the low balance notification. Zero credits pause message sending.
Save contato@timelyai.com.br in your incident contacts list. For critical issues, include “URGENT” in the subject line.

​
Visual summary

Secrets

API keys in environment variables, minimum scopes, webhook secret validated, rotation planned.

API

Correct production URL, retry with backoff, full pagination, timeouts configured.

Webhooks

Public endpoint, fast response, idempotency, failure log monitored.

Agents and channels

Tested with real-world scenarios, handoff configured, channel tested end-to-end, templates approved.
Checked everything? Go ahead. For any last-minute questions, reach us at contato@timelyai.com.br.