Changelog

How this changelog works

Entries are newest first. Each entry gives a date, a change type, and what you need to do. Breaking changes are called out first inside each date block.

Change types:

API versioning is covered in api-conventions. The version is part of the path (/api/v1). If a change below refers to a request or response shape, that page defines the shape.

What counts as breaking

These are treated as breaking and get advance notice:

• Removing a field from a response, or removing an endpoint.
• Changing the type of an existing field.
• Adding a required request parameter.
• Changing the meaning of an existing enum value.
• Changing an HTTP status code returned for an existing condition.

These are not treated as breaking, and can ship without notice:

• Adding a new field to a response body.
• Adding a new value to an existing enum.
• Adding a new optional request parameter.
• Adding a new webhook event type.
• Changing the wording of an error message string. The code is stable, the message is not. See api-errors.

The consequence for you: your JSON parsing must tolerate unknown fields, and your webhook handler must ignore event types it does not recognize rather than erroring. A handler that throws on an unknown event type will start failing and get retried on a schedule you did not choose. See webhook-events and webhook-retries.

A tolerant handler looks like this:

import express from "express";

const app = express();

app.post("/finn/webhook", express.json(), (req, res) => {
  const event = req.body;

  switch (event.event) {
    case "call.completed":
      handleCallCompleted(event);
      break;
    default:
      // Unknown or newly added event type. Acknowledge, do not throw.
      console.log("unhandled event", event.event);
  }

  res.status(200).send();
});

function handleCallCompleted(event: unknown) {
  // your logic
}

app.listen(3000);

Entries

No dated entries have been published here yet. When they are, they will follow the format above, newest first.

How to find out before something breaks

Polling this page is the weakest option. Better:

1. Keep a staging workspace with a separate API key and run your integration against it before you promote. See local-development for running against your own machine.
2. Write your client to tolerate unknown fields and unknown webhook event types, as shown above, so additive changes cannot break it.

Things that change without a changelog entry

Some behavior is per-workspace and will not appear here at all, because it is configuration rather than platform change:

If a call started failing and nothing on this page explains it, the cause is usually one of the above rather than a platform change. Start at troubleshooting, then check api-errors for the specific code you got back. If neither resolves it, support covers what to include in a report.