Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.usetitan.app/llms.txt

Use this file to discover all available pages before exploring further.

DB sync adapters are packages that translate incoming Titan webhook events into database writes. Instead of writing a webhook handler from scratch, you install the adapter for your platform, run its migration, deploy the handler, and register the URL with Titan. The adapter handles signature verification, deduplication, and mapping each event type to the right tables or collections. Every adapter provides the same three guarantees:
  • Webhook signature verification — requests with invalid HMAC-SHA256 signatures are rejected before any database write occurs.
  • Idempotent event processing — events are deduplicated by event ID, so replayed deliveries do not create duplicate records.
  • Event-to-database mapping — each event type (message.received, session.status, contact.update, etc.) is mapped to the appropriate tables or collections for your platform.

​
Available adapters

AdapterPackageDatabaseInstall
Supabase@titan-api/supabasePostgreSQL (Supabase)npm install @titan-api/supabase
Convex@titan-api/convexConvexnpm install @titan-api/convex
Firebase@titan-api/firebaseCloud Firestorenpm install @titan-api/firebase
Laraveltitan/laravelMySQL/PostgreSQLcomposer require titan/laravel
Cloudflare@titan-api/cloudflareD1 (SQLite)npm install @titan-api/cloudflare
Vercel@titan-api/vercelPostgreSQL (Vercel Postgres)npm install @titan-api/vercel
AWS@titan-api/awsDynamoDBnpm install @titan-api/aws
Azure@titan-api/azureCosmos DBnpm install @titan-api/azure
GCP@titan-api/gcpCloud SQL (PostgreSQL)npm install @titan-api/gcp
DigitalOcean@titan-api/digitaloceanManaged PostgreSQLnpm install @titan-api/digitalocean
Netlify@titan-api/netlifyNeon PostgreSQLnpm install @titan-api/netlify
All adapters except titan/laravel live in the titan-api/sdks monorepo under packages/.

​
How adapters work

When Titan delivers a webhook event to your endpoint, the adapter processes it in order:
  1. Receives the raw HTTP request from Titan
  2. Verifies the HMAC-SHA256 signature on the X-Webhook-Signature header
  3. Checks whether the event ID has already been processed (deduplication)
  4. Maps the event payload to one or more database writes
  5. Returns a 200 response to Titan
Your platform’s native real-time features — Supabase Realtime, Convex reactive queries, Firebase listeners — pick up the database changes and push updates to connected clients automatically.

​
Setup pattern

All adapters follow the same five-step setup. See each adapter’s README for platform-specific details.
1

Install the package

Install the adapter package for your platform using the command in the table above.
2

Run the migration or schema setup

Each adapter ships with a migration file or schema definition. Run it against your database to create the tables or collections the adapter writes to. SQL-based adapters provide a .sql file; platform-native adapters (Convex, Firebase) provide a schema definition file.
3

Deploy the webhook handler

Create a webhook endpoint using the handler exported by the adapter. The handler is a standard request handler for your platform — a Supabase Edge Function, a Vercel API route, a Cloudflare Worker, a Laravel route, and so on.
4

Register the webhook URL with Titan

Register your deployed endpoint with Titan so it knows where to deliver events:
curl -X POST https://api.example.com/api/webhooks \
  -H "Authorization: Bearer titan_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/api/titan-webhook",
    "events": ["*"],
    "secret": "your-webhook-secret"
  }'
5

Set the webhook secret environment variable

Set TITAN_WEBHOOK_SECRET to the secret you used when registering the webhook. The adapter reads this variable to verify incoming signatures.
TITAN_WEBHOOK_SECRET=your-webhook-secret
The events field on the webhook registration accepts "*" to subscribe to all event types, or an array of specific event names like ["message.received", "session.status"]. Subscribing only to the events your adapter actually maps to database records reduces unnecessary traffic.

​
What gets written to the database

Adapters map event types to database records. The exact schema depends on the platform, but all adapters cover the core event categories:
Event categoryWhat gets written
message.received, message.sentMessage records with sender, recipient, type, content, and timestamp
session.status, session.connectedSession state and connection history
contact.updateContact info including display name and profile picture URL
group.update, group.participantGroup metadata and participant lists
chat.archive, chat.mute, chat.readChat state flags
Titan does not store message content. Adapters write the event payload that Titan delivers — which is the message content your webhook receives at delivery time. If you need a full message archive, adapters are the recommended approach.