Fireblocks Integration

What Does the Integration Do?

Once connected, Corsa continuously syncs data from your Fireblocks workspace:

What Gets Synced

• Vault accounts — name, vault ID, customer reference ID, and all associated assets.
• Wallets — blockchain address, chain, associated vault, and asset type.
• Transactions — transaction hash, status, sub-status, amount, source/destination addresses, timestamps, operation type, and notes.

Real-Time Updates via Webhooks

In addition to periodic polling, the integration listens for Fireblocks webhook events for near real-time updates:

---

Setup Guide

Prerequisites

• A Fireblocks workspace with Admin or Non-Signing Admin access.
• Access to Corsa's Settings > Integrations page.

Step 1 — Create the Integration in Corsa

1. Navigate to Settings > Developers > Integrations in the Corsa dashboard.
2. Select Fireblocks from the available integrations.
3. Optionally configure the polling interval (how often Corsa syncs data from Fireblocks, in minutes). The default is 10 minutes.
4. Click Create.

Corsa will generate:

• A Certificate Signing Request (CSR) — needed to create an API user in Fireblocks.
• A Webhook URL — the endpoint Fireblocks will send events to.
• A list of webhook events — the events to enable in Fireblocks.

Step 2 — Create an API User in Fireblocks

1. In the Corsa integration setup screen, download or copy the CSR file.
2. Open the Fireblocks Console.
3. Go to Settings > Users > API Users.
4. Click Add API User.
5. Give the API user a name (e.g., Corsa Integration).
6. Upload the CSR file from Corsa.
7. Set the role to Viewer (required for full vault and transaction access).
8. Complete the API user creation.
9. Copy the API User ID (also called API Key) that Fireblocks provides.

Step 3 — Configure Webhooks in Fireblocks

1. In the Fireblocks Console, go to Settings > Webhooks.
2. Click Add Webhook.
3. Paste the Webhook URL provided by Corsa.
4. Enable the following events:
   • transaction.created
   • transaction.status.updated
   • vault_account.created (appears under wallets)
   • vault_account.asset.added (appears under wallets)
5. Save the webhook configuration.

Step 4 — Complete Setup in Corsa

1. Return to the Corsa integration setup screen.
2. Enter the Fireblocks API User ID (from Step 2).
3. Click Complete Setup.

The integration status will change to Active and the first data sync will begin automatically.

---

How It Works

Data Sync

Once active, the integration performs two types of syncs:

• Partial sync — Runs on the configured polling interval (default: every 10 minutes). Fetches only changes since the last sync.
• Full sync — Can be triggered manually. Re-syncs all vault accounts, wallets, and transactions.

During each sync, the service:

1. Fetches vault accounts from Fireblocks and creates/updates corporate clients in Corsa.
2. Fetches deposit addresses for each vault asset and creates/updates blockchain wallets.
3. Fetches recent transactions and creates/updates deposit and withdrawal records.

Webhook Processing

Webhook events are processed in near real-time. When Fireblocks sends an event:

1. The webhook signature is validated (RSA-SHA512 or JWKS-based verification).
2. The event is routed to the Fireblocks integration service.
3. The relevant data (transaction, vault, or wallet) is fetched from Fireblocks and synced to Corsa.

Entity Mapping

Vault Accounts → Corporate Clients:

• Each vault account becomes a corporate client in Corsa.
• If a customerRefId is set on the vault in Fireblocks, it is preserved and used for correlation.
• Custom fields include the Fireblocks vault ID and vault name.

Deposit Addresses → Blockchain Wallets:

• Each deposit address is tracked as a blockchain wallet.
• The wallet is associated with the corporate client that owns the vault.
• Chain detection is automatic based on the Fireblocks asset type.

Transactions → Deposits & Withdrawals:

• Incoming transfers to your vaults are mapped as deposits.
• Outgoing transfers from your vaults are mapped as withdrawals.
• Transaction metadata (status, sub-status, operation type, hash, notes) is preserved as custom fields.

---

Configuration Options

The polling interval can be updated at any time from the integration settings page.

---

Security

• API credentials are securely stored encrypted and never exposed in the Corsa UI after setup.
• Webhook signatures are cryptographically verified on every incoming event using Fireblocks' public keys.
• CSR-based authentication ensures the private key never leaves Corsa's infrastructure — only the CSR (public) is shared with Fireblocks.
• All communication with Fireblocks uses HTTPS/TLS.

---

Troubleshooting

Integration status is stuck on "Pending Setup"

Make sure you've completed all four setup steps, including entering the Fireblocks API User ID and clicking Complete Setup in Corsa.

Data is not syncing

• Verify the integration status is Active in Corsa.
• Check that the Fireblocks API user has proper role permissions.
• Ensure the API user is not disabled or expired in the Fireblocks Console.

Webhooks are not being received

• Confirm the webhook URL in Fireblocks matches the one provided by Corsa exactly.
• Verify all four required event types are enabled in the Fireblocks webhook configuration.
• Check that the webhook is not paused or disabled in the Fireblocks Console.

Missing vaults or wallets

• Vault accounts and wallets are synced during periodic polling. Wait for the next sync cycle or trigger a manual full sync.
• Ensure the vault accounts are not hidden in Fireblocks.

Transactions not appearing

• Only transactions involving your vault accounts are synced (not external wallet transfers).
• Transactions in very early states may appear after subsequent status updates.
• For immediate visibility, ensure webhooks are properly configured.