Best Practices

Follow these best practices to build a reliable, secure, and user-friendly Fiskil integration.

Security

Protect Your Credentials

• Never expose your client_secret in frontend code
• Store credentials in environment variables or a secrets manager
• Rotate API keys periodically (every 90 days recommended)

Server-Side Integration

• Make all API calls from your server, not the browser
• Use HTTPS for all communications
• Validate webhook signatures before processing

Handle Tokens Securely

• Don't store access tokens in browser storage
• Implement proper token expiry handling
• Never log tokens or credentials

Data Handling

Request Only What You Need

• Configure consent to request only essential data scopes
• Shorter consent periods are more user-friendly
• Limit data history to what's necessary

Cache Wisely

• Use webhook events to know when new data is available
• Don't poll APIs excessively
• Implement proper cache invalidation

Handle Data Updates

• Data can change between syncs
• Implement proper update/upsert logic in your database
• Consider soft deletes for removed records

User Experience

Clear Communication

• Explain what data you're accessing and why
• Be transparent about how data will be used
• Provide easy access to consent management

Error Handling

• Handle all error cases gracefully
• Provide helpful error messages to users
• Log errors for debugging

Loading States

• Show progress indicators during the Link flow
• Inform users when data is syncing
• Handle timeouts appropriately

Webhooks

Reliability

• Always return 2xx status codes promptly
• Process webhook payloads asynchronously
• Implement idempotency using message_id

Security

• Verify webhook signatures
• Only accept webhooks from Fiskil IPs
• Use HTTPS endpoints

Error Handling

• Handle retries gracefully
• Log failed webhook processing for investigation
• Monitor webhook delivery health

Testing

Use the Sandbox

• Test all flows in sandbox before production
• Create multiple test end-users for different scenarios
• Verify webhook delivery in sandbox

Test Edge Cases

• User cancellation
• Authentication failures
• Network errors
• Token expiry

Monitoring

Log Important Events

• API call successes and failures
• Webhook receipts
• Consent lifecycle events

Set Up Alerts

• Monitor for elevated error rates
• Track API latency
• Alert on webhook delivery failures