Best Practices

General guidelines for building reliable and forward-compatible third-party app integrations on the CRM platform.

---

Assume Non-Breaking Changes

The CRM platform may add new capabilities to its APIs and webhook events at any time without prior notice. These additions are considered non-breaking and will not be announced in advance. Your integration must be built to handle them gracefully.

What counts as a non-breaking change

The following changes may be made at any time:

• Adding new REST API endpoints.
• Adding new optional fields or headers to existing API request bodies.
• Adding new fields or headers to existing API responses.
• Adding new properties to webhook event objects.
• Reordering properties within API response bodies and webhook event objects.
• Adding new enumerated values, for example, a new type value inside a data payload.
• Minor variations in whitespace or formatting within JSON response bodies.

How to handle this in your integration

Ignore unknown JSON fields. Use a JSON deserializer that silently skips fields your code does not recognize. Never fail or throw on unexpected keys.

Handle unknown enum values. When switching or branching on a string enum, always include a default/fallback case. An unknown value should be logged and skipped, not cause a crash or an unhandled exception.

Do not assume field order. Treat JSON objects as unordered maps. Do not parse responses by position or rely on a specific serialization order.

Do not assert on response shape beyond what you use. Only validate the fields your code actually reads. Strict schema assertions against the full response body will break when we add new fields.

Example: If the CRM adds a new reply_to_id field to the message.created webhook event payload, your handler must deserialize successfully without explicitly mapping every field, parse what you recognize and ignore the rest.

---

Do Not Restrict Your Webhook Endpoint by IP Address

Do not configure your webhook server to only accept requests from a fixed set of CRM IP addresses. The CRM's outbound IP addresses are not published and may change at any time without notice, an IP allowlist will eventually block legitimate webhook deliveries.

Use signature verification instead. Every CRM webhook includes a X-Data-Signature header containing an HMAC-SHA256 digest of the raw request body. Verifying this signature cryptographically proves the request came from the CRM and has not been tampered with. This is both more reliable and more secure than IP filtering.

See CRM Webhooks for full implementation details and code examples.