Internal API Spec
This page summarizes the conventions that sit under the current API routes.Authentication
- internal operator endpoints are a staging surface and should end up behind Supabase session enforcement or signed bearer authentication
- webhook endpoints validate provider signatures before accepting deliveries
- compatibility endpoints are expected to use scoped API keys per caller
Response conventions
- compatibility responses should stay boring and machine-readable
- validation failures should return structured error details
- replay and operator endpoints should include stable identifiers for audit and retry tracing
- request correlation belongs in logs and response payloads where useful
Endpoint families
Provider ingress
/webhooks/meta/webhooks/whatsapp
Compatibility
/compat/contact/compat/journey-trigger/{legacyPath}
Operator and runtime
/internal/runtime/internal/operations/internal/conversations/internal/webhooks/internal/webhook-events/internal/webhook-rejections/internal/outbox/internal/audit-logs
Replay model
- replay creates a new processing attempt rather than mutating the original delivery
- deduplication keys remain explicit
- audit logs should show who replayed what and why