API Integration Guides.
Practical, vendor-neutral guidance for connecting business systems: authentication, webhooks, retries and idempotency, data mapping, and error handling. Code examples in the linked articles were tested before publication.
Authentication
Most business APIs use either API keys (a secret string sent in a header) or OAuth 2.0, where a user authorizes your application and you receive short-lived access tokens plus a refresh token.
Store credentials in environment variables or a secret manager — never in source code or client-side JavaScript — and request the narrowest scopes that do the job.
Webhooks
A webhook is an HTTP request another system sends to your endpoint when an event occurs. Verify every request’s signature, respond with a 2xx quickly, and process the event asynchronously.
Expect duplicates and out-of-order delivery: record event IDs and compare timestamps before overwriting data.
Retries & idempotency
Retry only temporary failures (timeouts, 429, 5xx) with exponential backoff and jitter. For requests that create things, send an idempotency key so a retried request is not applied twice.
Data mapping & transformation
Write mappings down explicitly: which system owns each field, how types and formats convert (for example decimal strings to integer minor units, lower-case to ISO currency codes), and what happens when a value is missing.
Keep a stable cross-reference such as external_ref so records can be matched and updated rather than duplicated.
// Source (CRM deal) // Destination (finance invoice)
{ {
"deal_id": "D-1042", "external_ref": "crm:D-1042",
"amount": "4200.00", "amount_minor": 420000,
"currency": "eur", "currency": "EUR",
"closed_at": "2026-10-18T09:12:44Z", "issue_date": "2026-10-18",
"contact": { "email": "[email protected]" } "customer_email": "[email protected]"
} }Error handling
Distinguish errors you can fix by changing the request (4xx) from errors worth retrying (5xx, timeouts). Many APIs return machine-readable problem details (RFC 9457); log the full response so failures can be investigated.
HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json
{
"type": "https://example.com/problems/invalid-field",
"title": "Invalid field",
"status": 422,
"detail": "invoice.currency must be a 3-letter ISO 4217 code",
"instance": "/invoices/requests/8f1c2b7e"
}Troubleshooting checklist
- 401/403: check the credential, its scopes, and whether it has expired or been rotated.
- 429: slow down, honour Retry-After, and spread scheduled jobs out.
- Duplicates: confirm idempotency keys are reused across retries and event IDs are de-duplicated.
- Missing records: check pagination and polling cursors, and reconcile periodically against the source.
Articles for integration engineers.
Webhooks vs. Polling: How to Choose for an API Integration
Compare webhooks and polling for API integrations: latency, reliability, cost, and failure modes — with tested code for idempotent handlers and cursor-based polling.
How to Design Reliable Retry Logic with Idempotency Keys
Learn when to retry failed API requests, how exponential backoff with jitter works, and how idempotency keys prevent duplicate payments or records. Tested Node.js code.
How to Verify Webhook Signatures with HMAC-SHA256
Step-by-step guide to verifying webhook signatures with HMAC-SHA256: raw request bodies, timestamp checks to stop replays, and constant-time comparison. Tested code.
Talk to an engineer.
If you are planning an integration with Finvercel products, contact us for technical documentation and help with your use case.