Weavr as your source of truth

Every feature in this blueprint eventually shows the customer some data that Weavr owns - a balance, a card's status, a customer's spend limits, their KYCKYC Know Your Customer - the identity verification process for consumer identities. This process allows you to seamlessly and securely verify your user's identity. Weavr will ask users to submit the necessary information and documentation so that they can get approved by financial providers. state. Any screen that displays that data has to get it from somewhere at the moment it renders. Where it comes from is an architectural choice, and it shapes your whole integration.

There are two ways to answer it. We strongly recommend the first.

Two ways to get Weavr data

Approach	Where your UI reads from	Our recommendation
Read on demand	Your backend calls our API when the screen needs the data	Recommended - our API is the source of truth
Mirror and sync	Your backend serves a copy from your own store, kept in sync by webhooks	Discouraged - your copy drifts from ours

Both put your backend between our API and your UI - that part never changes. Your client should never call our API directly; that rule holds everywhere in the app. What differs is when your backend reads from us, and whether your UI trusts our data or a copy of it.

Read on demand (recommended)

When a screen needs Weavr-owned data, your backend fetches it from our API right then and passes it to your UI. Take a spend limits screen as the example:

1. The customer opens the spend limits screen in your app.
2. Your backend calls our API to get the current spend limits.
3. You render what we return.

The data on screen is whatever our API returns at that moment, so it's correct by construction. There's nothing to keep in sync, nothing to reconcile, and no window in which your customer sees a value we no longer hold. This is the model to reach for by default.

Mirror and sync (discouraged)

The alternative keeps a copy of our data in your own store and renders from that copy. Webhooks tell you when to refresh it. The same spend limits screen looks like this:

1. Ahead of time, a spend limit updated webhook fires.
2. Your backend calls our API to get the current spend limits.
3. Your backend writes a copy to your own database.
4. Later, the customer opens the spend limits screen.
5. You render the spend limits from your copy.

In effect, you rebuild a slice of our database inside your own systems - a data lake - and then take on the job of keeping it faithful to ours. The screen no longer shows our data; it shows your copy of our data, which is only as fresh as your last successful sync.

Why we discourage mirroring

Mirroring turns one source of truth into two, and now they can disagree. Every gap in the sync becomes a moment when your customer sees something that isn't true.

Webhooks are designed to drive reactions, not to replicate a database. Leaning on them for sync means inheriting their delivery characteristics:

• Delivery is at-least-once, not exactly-once. The same event can arrive more than once, so your sync has to be idempotent.
• Order isn't guaranteed. Events can arrive out of sequence, so a later update can overwrite a newer value with an older one unless you guard against it.
• Delivery can fail entirely. After six failed attempts an event is marked failed and we stop retrying. Miss one and your copy silently diverges, with nothing on screen to signal it's wrong.

Even when delivery goes perfectly, you've signed up for reconciliation, backfills, and schema migrations that track ours - real, ongoing engineering that produces, at best, a slightly-behind copy of data you could have read directly. The failure mode is quiet and expensive: a customer acting on a stale spend limit, a balance that's minutes behind, a card shown as active after it was frozen.

Our API is the source of truth

Read from our API when you need the data. Don't stand up a shadow copy and keep it in sync with webhooks - that duplicates our database in your ecosystem and makes your app only as correct as your last sync.

What webhooks are for

Webhooks are the right tool for a different job: reacting to something the moment it happens. Use them to drive business logic - work your app does in response to an event, not a mirror of our state. For example:

• Notify your customers in real time - a spend alert, a "funds received" push, a KYCKYC Know Your Customer - the identity verification process for consumer identities. This process allows you to seamlessly and securely verify your user's identity. Weavr will ask users to submit the necessary information and documentation so that they can get approved by financial providers.-approved email. See notify your customers in real time.
• Kick off a workflow - start fulfilling an order when a payment settles, open a review task when verification needs attention, unlock a feature when onboarding completes.
• Refresh a live screen - when a customer already has an activity feed open, use the event as the cue to re-read and refresh, rather than polling. See keeping views fresh with webhooks.

In all of these, the webhook is a trigger. When you then need the underlying data, you read it from our API - the event tells you that something changed, and our API tells you what it now is.

When storing data is legitimate

Some cases genuinely call for keeping data of your own, and that's fine. Storing your own records - reconciliation ledgers, analytics, an audit trail, references you map to your customers - is expected, and some of it you're obliged to keep. Short-lived caching to smooth out a burst of reads is reasonable too.

The line is this: store what you need for your own purposes, but don't treat that store as the truth about our data. When a screen shows a customer the current state of something we own - a balance, a limit, a status - read it from us. If you cache, cache with a short life and a clear understanding that our API remains authoritative, not the other way round.

In short

• Read Weavr data on demand from your backend, and treat our API as the source of truth.
• Don't mirror our data into your own store and keep it in sync with webhooks - the copy drifts and your customers see stale state.
• Use webhooks to drive business logic - notifications, workflows, refreshing a live screen - not to replicate our database.

With this principle in hand, the next page puts it to work on the read-heavy screens of the app - the activity feed and statements.