Best Practices

API Versions

All the events sent by Circuit API will be versioned. The version defines how the body of the message you receive should be handled, and what fields it contains.

The versions have the following format: v0.Xb where X denotes in which beta version the API is in. This format will change once the API comes out of beta, but for now you should expect this to be true.

Circuit will never send an event in a version you didn't ask for, this version can be set on the Circuit For Teams settings page.

info

Circuit will not bump the version for every type of change, see the Changelog for more details on this.

Event types

You should only get from the events you receive the important fields for your logic to work.

You also should ignore any events not important for your use case.

Parsing or checking the data on fields and events you don't need may put undue stress on your side.

To check what event types Circuit sends take a look at the Webhook Events section.

Delivery attempts

If your endpoint is down or not responding with a 2xx code, Circuit will keep retrying the delivery of the messages by around an hour. The retries have an exponential backoff independent for each message.

After the 1-hour period is over, Circuit will stop trying to deliver the message and discard it.

Due to the fast nature of delivery events we consider 1 hour to be enough time for the message to still be relevant and be retried.

Handling the Events

Due to the distributed nature of our internal systems, there may be some edge cases happening.

Out Of Order Delivery

The delivery of the messages to your endpoint may come out of order from the actual order the events themselves occurred. If ordering is important for your internal systems you should set up a system to handle this case.

We strongly recommend you don't do that though. It may put undue strain on your systems to order the messages you receive. We recommend you project a system as stateless as possible to prevent unforeseen edge-cases.

Duplicate Delivery

Some messages may be delivered more than once, though rare, this can happen. Thus, we recommend your systems are able to handle the received messages in an idempotent manner. One way to do this is storing the events you received and if you receive one that is already stored, you may discard it and answer with a 2xx code.

Secure connections

Circuit will outright refuse any non-encrypted connection. So be sure that HTTPS is enabled on your endpoint, even if with a self-signed key.

Redirects and other HTTP statuses

Circuit will consider any status different from 2xx statutes an error. This also means circuit will not follow any redirects, considering a redirect status an error, and will keep retrying until the status is 2xx or the retry window expires.