Audit events

BlendFi keeps an append-only audit log of every state change in platform resources: user creation, KYC status change, quote creation and consumption, transaction transitions, conversion transitions, webhook processing, administrative actions. Every event is immutable and retained for years.

Why it exists

Three forces shape the audit log:

• Regulatory retention. BlendFi is regulated by the Brazilian Central Bank. Regulation mandates that records remain available to the regulator for at least five years. The audit log is the durable source for that obligation.
• Continuous monitoring. Regulation requires uninterrupted visibility over institutional activity. A uniform append-only event stream is the mechanism that meets that requirement.
• Forensics and support. When a partner reports that a quote was unexpectedly consumed, or an operator needs to know who approved a KYC, the log is the authoritative record. It answers the canonical question: who did what to which resource at what time, and what did it look like before and after.

The design principle: we audit at the point of business decision, not at the database layer. Each event represents a decision that happened, not a SQL operation. That is what regulators, support, and partners actually want to read.

What gets recorded

Every mutation on a platform resource emits an event:

• User lifecycle: creation, update, soft-delete, KYC submission start, KYC status change.
• Quote lifecycle: creation, consumption, expiration, cancellation.
• Transaction and conversion lifecycle: every state transition, including failure terminals.
• Webhook processing: every external event that resulted in a state change.
• Administrative actions: operator overrides, resolutions, suspensions.

What does not enter the log:

• Reads (GET). The audit covers state changes, not access.
• Failed authentication attempts. Those go to the security log, not the business trail.
• Internal intermediate computations that don't persist state.

What each event carries

Every event has uniform fields that make forensic reading direct:

• Actor: who performed the action (an organization API key, a BlendFi operator, an internal system, an external service, an end user).
• Action: stable readable name of the operation, in resource.event shape. Examples: user.created, quote.consumed, conversion.completed, user.kyc_approved.
• Resource: type and identifier of the affected resource.
• Before state and after state: a sanitized snapshot of the fields that changed. Identifiers and sensitive data (full CPF, secrets, keys) are excluded by design.
• Context: request_id correlating to the originating HTTP request, IP and user-agent when applicable.
• Timestamp: instant of the decision, in UTC.

Invariants

These guarantees hold for every event. They are contractual:

• Append-only. The events table rejects UPDATE, DELETE, and TRUNCATE, including for super-users. Corrections happen by emitting new events that describe the correction, never by mutating prior ones.
• Every state change emits exactly one event. Idempotent operations (retry with the same Idempotency-Key) do not re-emit.
• No PII or secrets in the record. Snapshots are sanitized at the source. Full CPF never appears; webhook secrets never appear; API keys never appear.
• Action names are stable. They are part of the operational contract. New names may be added, never renamed.

How your organization interacts with the log

Today, querying the log goes through BlendFi's team:

• Support and investigation. On support tickets, the BlendFi team queries the log by request_id or by the resource id and returns the timeline of transitions. If you shared a request_id (every error response carries one), the investigation is direct.
• Formal audit requests. For cases that require documentary evidence (internal audit, regulatory request), the team produces the report from the log scoped to what was requested.

Next steps

• Webhooks: every webhook event you receive has a corresponding entry in the log.
• Errors and retries: every error response carries request_id, which is the key to locating your call in the log.