API and webhook business guide

Agree the business contract first

Why this matters: A technically successful connection can still create business risk if ownership, data purpose, and failure handling are unclear.

• Define which records move, in which direction, and for what purpose.
• Name the business owner and technical owner.
• Decide what should happen if either system is unavailable.
• Set retention, privacy, and audit requirements.
• Use a test environment or safe records before production data.

API access in simple terms

Create a service account for the integration, give it only the required permission and organization scope, and store the one-time key in an approved secret manager. Do not reuse a staff login or place the key in source code.

Prevent duplicates and unsafe retries

• Use an idempotency key when a write may be safely retried.
• Pause and retry gradually after temporary failures or rate limits.
• Record request IDs for investigation without logging credentials or sensitive content.
• Treat a timeout as an unknown result until the system confirms whether the action completed.

Verify every webhook

The receiving system should verify Acerite’s signature against the original message, reject old or replayed deliveries, and use the event ID to avoid processing the same event twice. Return success only after the event has been safely accepted.