​

Build an integration

Start with the operating contract, not the endpoint list. A reliable integration makes it clear which system owns each record, what RevDesk may change, and how both systems recover when a request fails.

​

Integration checklist

1. Name the workflow. Define the trigger, audience, expected outcome, and human escalation path.
2. Choose the system of record. Decide which system owns the customer, opportunity, appointment, and consent state.
3. Limit access. Request only the organizations, locations, objects, fields, and actions the workflow needs.
4. Define identity. Choose the stable external identifiers used to match and deduplicate records.
5. Write down write-back. List every field RevDesk may create or update, including stage, owner, activity, appointment, and next step.
6. Design retries. Make repeated requests safe and keep enough context to reconcile a partial failure.
7. Test the exception path. Verify missing records, revoked access, invalid data, rate limits, timeouts, and duplicate events.
8. Add operational visibility. Record request identifiers, outcome, latency, and the person or workflow responsible for recovery.

​

Recommended build path

​

Data and identity contract

Write down the contract before sending production data:

• Which organization and, when applicable, location owns each record
• Which system owns customer, opportunity, appointment, consent, and communication state
• The stable identifiers used to match and deduplicate records
• Required, optional, immutable, and sensitive fields
• The direction of each supported write and how conflicts are resolved
• The event or reconciliation process that repairs missed updates

Use organization-scoped credentials and request only the scopes required by this contract. A successful API request does not grant permission to copy unrelated fields into another system.

​

Events and webhooks

Use webhooks when another system needs to react to RevDesk activity without polling. A consumer should accept the event durably, process it idempotently, and preserve enough evidence to diagnose or replay a failure.

1. Verify the webhook signature before parsing or acting on the payload.
2. Persist the event identifier, organization, event type, received time, and processing state.
3. Return success only after the event is accepted for durable processing.
4. Treat duplicate and out-of-order delivery as normal.
5. Fetch current resource state when the latest state matters more than the event snapshot.
6. Retry transient failures with bounded backoff and route permanent failures to a visible review queue.

Do not place credentials, full payloads, or broad customer records in logs. Use request and event identifiers to connect sanitized application logs to the affected record.

​

Recovery and reconciliation

Retries cover temporary failures; reconciliation covers failures you did not observe. Keep a cursor or time window that lets an operator compare the source and destination, identify missing or conflicting records, and replay only the affected work. Reconciliation must use the same ownership and idempotency rules as the live path. Define who owns each recovery queue, how long failures may remain unresolved, and which corrections require a person. Never make a broad overwrite the default response to a partial mismatch.

​

Testing and production readiness

Test the business outcome across both systems, not only the successful HTTP response. Before production:

1. Run the complete flow with test records.
2. Compare the final state in RevDesk and the connected system.
3. Confirm replaying a request or event does not duplicate work.
4. Verify revoked or insufficient credentials fail closed.
5. Exercise the reconciliation path.
6. Start with a controlled audience or one location and monitor the first production window.