API Versioning

1. Overview

At Devengo, our public API is our product.

It evolves continuously to meet new business requirements and adapt to regulatory and operational changes. At the same time, it requires ongoing refinement to prevent unnecessary complexity resulting from past design decisions made in different contexts.

This document defines Devengo’s API Versioning Policy, with the following goals:

1. Predictability and Stability — Clients can trust that their integrations will remain stable, and they will know when and how to expect new versions of the API.
2. Consistency for Product & Engineering — The Product and Engineering teams have a clear, shared framework for deciding when and how to release new changes.
3. Internal Alignment — This policy also serves as an implementation guide for Devengo’s development team, defining the standards and infrastructure needed to support API versioning, changelogs, and controlled evolution of the platform.

2. Release Cycle

New versions of the API are released on a monthly schedule, ensuring a continuous flow of improvements and incremental updates without disrupting existing integrations.

Most monthly releases introduce non-breaking changes — such as new optional fields, performance optimizations, or additional endpoints — allowing clients to benefit from enhancements without the need for immediate action. These releases are designed to be fully backward-compatible, so existing integrations continue to operate seamlessly.

Devengo aims to minimize the frequency of breaking changes, but due to the nature of financial and regulated environments, certain updates may be required to comply with regulatory mandates. When such cases occur, Devengo will announce them in advance, provide Beta endpoints in the Sandbox environment, and define a migration period specific to that release.

Each release is accompanied by a public changelog describing the scope of the changes, migration steps if applicable, and the effective dates for the new and deprecated versions. This predictable release model gives clients confidence that their integrations will remain stable while providing a controlled path for continuous improvement and compliance.

3. What is a Breaking Change

A breaking change is any modification to the existing API schema or behavior that can cause an integration using a previous version to fail, behave unexpectedly, or produce validation errors.

In practical terms, this includes any change that modifies or removes an existing attribute, alters its data type, or changes the structure of an existing response or request body.
For example, changing a field from an integer to an object, or renaming a top-level attribute, would both be considered breaking changes.

By contrast, additive changes — such as introducing new optional attributes, adding new endpoints, or extending existing responses with additional metadata — are not considered breaking, as they preserve backward compatibility and do not impact existing integrations.

Note: If your implementation uses strict schema validation that rejects unexpected fields, you may experience breaking behavior from changes we classify as non-breaking. We recommend lenient validation that accepts additional fields in responses.

4. How We Version the API

Each version of the API is explicitly linked to an API Key. When a client wishes to start using a newer version, they must generate a new API Key associated with that version. This ensures clear version isolation and allows clients to migrate gradually and safely across versions without affecting their existing integrations.

5. Webhooks and Versioning

Webhooks in Devengo are version-bound and follow the same versioning principles as the API. The version of a webhook must always correspond to an existing API Key owned by the client.

When creating a webhook, the list of available versions is automatically restricted to the API versions associated with the client’s active API Keys. For example, if a client only holds an API Key for version 2025-03, they can only create webhooks using that same version. This ensures consistency between the data formats of API responses and webhook event payloads.

If a client generates a new API Key for a later version (for instance, 2025-09), they can begin creating webhooks under that version, test them in the Sandbox environment, and progressively migrate their event handling logic. Once the migration is complete, older webhooks tied to deprecated API versions should be deleted to prevent inconsistencies.

In the event of a regulatory or mandatory migration, Devengo will provide early communication and Beta endpoints in Sandbox, allowing clients to adapt their webhook integrations well before enforcement. Once the migration window closes, webhook deliveries for deprecated versions will stop, and events will only be emitted for active API versions.

6. Communication & Support

Devengo ensures that all changes to the API are communicated clearly and proactively to clients, providing both transparency and guidance for upgrades. With each new version of the API, a detailed changelog is published in the public documentation.

In addition to the public changelog, Devengo also notifies all active clients via email whenever a new version is released, ensuring that all integrations are aware of updates and have sufficient time to plan migrations.

To support the structured deprecation of older versions, responses from deprecated endpoints include the Deprecation and Sunset headers, indicating the version’s pending retirement and the final date after which it will no longer be available. Once the sunset date has passed, calls to the deprecated version will return a 410 Gone status, accompanied by a descriptive message informing the client that the version has expired and guiding them to the successor version.

This approach ensures that clients are never caught by surprise, that migrations can be planned safely, and that the lifecycle of each version is fully transparent.