How to sync transactions to your database

This guide shows you how to keep your database in sync with each user's transactions. Quiltt sends a webhook whenever a Connection syncs; your handler fetches the new transactions and stores them.

The handler you build:

1. Receives connection.synced.successful webhooks when transaction data changes
2. Authenticates server-to-server with Basic Auth (no Session token rate limits)
3. Fetches transactions from the GraphQL API, paging through every result
4. Uses the event's date-range metadata to fetch only what changed
5. Stores transactions idempotently, so retried webhooks never create duplicates

The examples use Node.js 18+, but the patterns apply to any backend.

Link to this section#How transaction sync works

Quiltt syncs financial data in the background after a user connects an account. Rather than poll the API on a timer, you subscribe to webhooks and react when data is ready:

1. A user connects an account through the Connector.
2. Quiltt syncs the Connection and sends a connection.synced.successful webhook.
3. Your handler verifies the webhook, then queries the Transactions API for that Profile.
4. You upsert the results into your own store.

The connection.synced.successful event family tells you what changed:

When an event carries metadata.startDate and metadata.endDate, fetch only that range. When it doesn't, the Connection is already up to date and no transactions need fetching.

Link to this section#Prerequisites

• Quiltt Dashboard account (sign up)
• A Connector with at least one connected account (see the Connectors tutorial)
• An API Key secret from the Dashboard
• Node.js 18 or higher
• A publicly reachable URL for local testing (use a tunneling tool such as ngrok)

Add your credentials to a .env file:

# .env
QUILTT_API_KEY_SECRET=your_api_key_secret_here
QUILTT_WEBHOOK_SECRET=your_webhook_subscription_secret_here

Link to this section#1. Subscribe to sync events

Create a webhook subscription that points at your handler. In the Dashboard:

1. Open the Webhooks link within your Environment.
2. Click Create Webhook Subscription.
3. Set the target URL to your handler endpoint (for example, your ngrok URL plus /quiltt_webhook).
4. Subscribe to connection.synced.successful. This automatically includes every connection.synced.successful.* event.
5. Copy the subscription secret into QUILTT_WEBHOOK_SECRET.

For programmatic setup, see the Webhooks setup guide.

Link to this section#2. Authenticate server-side

Server-to-server requests to a Profile's data use Basic Auth, which is not subject to the per-Profile Session token rate limits. Encode profileId:API_KEY_SECRET as Base64 and send it as the Authorization header:

// quiltt.ts
const GRAPHQL_ENDPOINT = 'https://api.quiltt.io/v1/graphql'

function authHeader(profileId: string): string {
  const encoded = Buffer.from(
    `${profileId}:${process.env.QUILTT_API_KEY_SECRET}`
  ).toString('base64')

  return `Basic ${encoded}`
}

See the Authentication guide for the full list of scopes and headers.

Link to this section#3. Fetch transactions with pagination

The transactions query uses cursor-based pagination, capped at 100 records per page. Page through the results with pageInfo.endCursor until hasNextPage is false.

This function fetches every transaction for a Profile within an optional date range:

// quiltt.ts (continued)
const TRANSACTIONS_QUERY = `
  query SyncTransactions($after: String, $filter: TransactionFilter) {
    transactions(first: 100, after: $after, sort: DATE_DESC, filter: $filter) {
      edges {
        node {
          id
          date
          description
          amount
          entryType
          status
          account {
            id
            name
          }
        }
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
`

type DateRange = { startDate?: string; endDate?: string }

export async function fetchTransactions(profileId: string, range: DateRange = {}) {
  const filter =
    range.startDate && range.endDate
      ? { date_gte: range.startDate, date_lte: range.endDate }
      : undefined

  const transactions = []
  let after: string | null = null

  do {
    const response = await fetch(GRAPHQL_ENDPOINT, {
      method: 'POST',
      headers: {
        Authorization: authHeader(profileId),
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        query: TRANSACTIONS_QUERY,
        variables: { after, filter },
      }),
    })

    const { data } = await response.json()
    const page = data.transactions

    transactions.push(...page.edges.map((edge) => edge.node))
    after = page.pageInfo.hasNextPage ? page.pageInfo.endCursor : null
  } while (after)

  return transactions
}

Link to this section#4. Store transactions idempotently

Each Transaction has a stable id. Quiltt retries failed webhook deliveries up to 20 times, so the same transaction can arrive more than once. Upsert on the id to keep your store consistent:

// store.ts
import { fetchTransactions } from './quiltt'

export async function syncTransactions(profileId: string, range = {}) {
  const transactions = await fetchTransactions(profileId, range)

  for (const transaction of transactions) {
    // Replace with your database's upsert.
    // Keying on transaction.id makes repeated syncs safe.
    await db.transactions.upsert({
      where: { id: transaction.id },
      update: transaction,
      create: { ...transaction, profileId },
    })
  }

  return transactions.length
}

Link to this section#5. Handle the webhook

Verify every incoming webhook before acting on it, then route connection.synced.successful events to your sync function. Pass the event's date metadata through so historical syncs fetch only the affected range:

// server.ts
import express, { Request, Response } from 'express'
import crypto from 'crypto'
import { syncTransactions } from './store'

const app = express()
const PORT = 3000

const QUILTT_WEBHOOK_SECRET = process.env.QUILTT_WEBHOOK_SECRET
const QUILTT_WEBHOOK_VERSION = 1
const QUILTT_WEBHOOK_WINDOW = 300 // Five minutes

const processedEvents = new Set<string>()

app.use(express.json())

app.post('/quiltt_webhook', async (req: Request, res: Response) => {
  const timestamp = req.header('Quiltt-Timestamp')
  if (!timestamp || Date.now() / 1000 - Number(timestamp) > QUILTT_WEBHOOK_WINDOW) {
    return res.status(204).send()
  }

  const payload = JSON.stringify(req.body)
  const signature = crypto
    .createHmac('sha256', QUILTT_WEBHOOK_SECRET)
    .update(`${QUILTT_WEBHOOK_VERSION}${timestamp}${payload}`)
    .digest('base64')

  if (req.header('Quiltt-Signature') !== signature) {
    return res.status(204).send()
  }

  // Acknowledge within 20 seconds, then process.
  res.status(204).send()

  for (const event of req.body.events) {
    // Skip events you've already processed (Quiltt retries deliveries).
    if (processedEvents.has(event.id)) continue
    processedEvents.add(event.id)

    if (event.type.startsWith('connection.synced.successful')) {
      const profileId = event.profile.id
      const range = event.metadata ?? {}

      const count = await syncTransactions(profileId, range)
      console.log(`Synced ${count} transactions for ${profileId}`)
    }
  }
})

app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`)
})

Link to this section#Verification

Test the full flow end to end:

1. Start your server and expose it with a tunnel:

   node server.js
   ngrok http 3000
   

2. Confirm the subscription's target URL points at your tunnel URL.

3. Connect an account in the Dashboard Connector preview. In a SANDBOX Environment, use the Mock provider for guaranteed data.

4. Watch your server logs. Within a few seconds you should see a connection.synced.successful.initial event and a count of synced transactions.

5. Query your database to confirm the transactions were stored.

Link to this section#Troubleshooting

Link to this section#Next steps

You now sync transactions automatically whenever a user's data changes. The same pattern works for other Profile data—swap the query and the event type.

Link to this section#Related tutorials

• Authentication Tutorial - Session token setup and management
• Multi-Aggregator Connectors Tutorial - Build a full connection flow
• Account Statements Tutorial - Fetch and display account statements

Link to this section#Reference documentation

• Transactions API reference - Complete transactions documentation
• Pagination guide - Cursor-based connections in depth
• Webhooks guide - Event types, payloads, and verification
• Authentication guide - Scopes, Basic Auth, and Session tokens

Link to this section#Questions?

Contact support