Webhooks

Receive signed HTTPS notifications for account grants, sync, account resources, orders, and reauth.

Finatic can POST JSON events to an HTTPS endpoint you control whenever subscribed account grants, sync state, account resources, orders, or reauth requirements change. Delivery is handled by FinaticBackground and is scoped to company account grants.

Configure subscriptions

Create and manage webhook endpoints in the Finatic dashboard under Settings → Webhooks for your team workspace.

For each subscription you provide:

URL — Must be HTTPS.
Environment — live or sandbox.
Event types — One or more event strings from the catalog below.
Secret — Used to compute X-Finatic-Signature.

The public event catalog is available at GET /api/v1/webhooks/catalog (no auth required). Subscription management is performed through the dashboard.

Event catalog

The canonical catalog is available at /api/v1/webhooks/catalog.

Account grants

account.grant.created
account.grant.updated
account.grant.revoked

Account sync

account.sync.started
account.sync.succeeded
account.sync.failed

Account resources

account.balance.updated
account.position.updated
account.transaction.created

Orders

order.created
order.updated
order.filled
order.cancelled
order.rejected

Connections

connection.reauth.required

Request shape

Each POST body is a JSON object with:

schemaVersion — currently v1.
eventId — unique event id.
eventType — subscribed event string.
createdAt — ISO timestamp.
environment — live or sandbox.
companyAccountId — company workspace that owns the grant/subscription.
accountId — financial account ID when the event is account-scoped.
grantId — account grant ID when available.
resource — resource pointer with resourceType, resourceId, accountId, and grantId.
data — event-specific payload.

Example:

{
"schemaVersion": "v1",
"eventId": "evt_01HX...",
"eventType": "order.filled",
"createdAt": "2026-06-08T20:15:00Z",
"environment": "live",
"companyAccountId": "acct_company_123",
"accountId": "acct_financial_456",
"grantId": "grant_789",
"resource": {
"resourceType": "order",
"resourceId": "order_abc",
"accountId": "acct_financial_456",
"grantId": "grant_789"
},
"data": {
"status": "FILLED",
"symbol": "AAPL"
}
}

Headers

Finatic sends at least:

Content-Type: application/json
User-Agent: Finatic-Webhooks/3.0
X-Finatic-Event
X-Finatic-Event-Id
X-Finatic-Delivery
X-Finatic-Signature: sha256=<hex>

X-Finatic-Signature is included when a subscription secret is configured.

Verify signatures

The signature is HMAC-SHA256 over the exact UTF-8 JSON body Finatic posts. Acknowledge quickly with any HTTP 2xx and process expensive work asynchronously.

import { createHmac, timingSafeEqual } from 'node:crypto';

export async function POST(request: Request) {
const rawBody = await request.text();
const signature = request.headers.get('x-finatic-signature') ?? '';
const expected = `sha256=${createHmac(
'sha256',
process.env.FINATIC_WEBHOOK_SECRET!,
)
.update(rawBody, 'utf8')
.digest('hex')}`;

const valid =
signature.length === expected.length &&
timingSafeEqual(Buffer.from(signature), Buffer.from(expected));

if (!valid) {
return new Response('invalid signature', { status: 401 });
}

return new Response('ok', { status: 200 });
}

Retries and idempotency

The worker treats any HTTP 2xx response as success. On timeouts, transport errors, or non-2xx responses, Finatic retries with exponential backoff. Use eventId as your idempotency key and store the latest processed event per resource if your workflow is order-sensitive.

Testing

Use sandbox subscriptions while you iterate.
Use dashboard test sends to validate endpoint routing and signature handling.
Confirm your handler routes by companyAccountId, accountId, and grantId.
Do not use provider connection IDs in webhook routing logic.

Next steps

Account-First Model — Understand public identity fields.
Account Grants — Manage grant scopes and disconnect behavior.
API Reference — Explore the webhook event catalog.