Depending on the extensions added to an app, Canva may send HTTP requests to a web server. You can configure the URL of this web server via the Developer Portal on a per-extension basis.

This page contains some essential things to know about the interactions between Canva and your app’s server.

Requests

Canva mostly sends requests to an app's server, rather than the reverse. This means most requests are outbound (from Canva to the app) and not inbound (from the app to Canva). It’s only in certain situations that apps send requests to Canva, such as at the end of an authentication flow.

When Canva sends requests:

• The request bodies are serialized as JSON.

• The properties in the request body depend on:

  • The endpoint receiving the request.

  • How the extension is configured via the Developer Portal.

  • The action taken by the user (e.g. when a user searches for something, the request body includes a query property).

Base URL

Canva doesn’t send all requests to a single endpoint. Instead, developers provide a Base URL for each of the app’s extensions. Then, when sending requests, Canva appends a path to the Base URL. This path identifies:

• The purpose of the request.

• The structure of the request that Canva sends.

• The structure of the response that Canva expects to receive.

To learn more, see Base URL.

Responses

Apps must respond to requests with JSON bodies. The body must include a type property that identifies if the request was successful or not.

Successful responses

If the value of the type property is "SUCCESS", the response body must conform to a schema that is (typically) determined by the path of the request. The exact schemas are detailed in the API reference documentation.

This is an example of a "SUCCESS" response for the /publish/resources/upload endpoint:

{
  "type": "SUCCESS",
  "url": "https://..."
}

Unsuccessful responses

If the value of the type property is "ERROR", the response must contain an errorCode property that indicates what went wrong. The supported error codes are listed in the API reference documentation.

This is an example of an "ERROR" response:

{
  "type": "ERROR",
  "errorCode": "INVALID_REQUEST"
}

Status codes

Canva expects endpoints to respond to requests with a 200 status code — even if an error has occurred. The only exception to this rule is when a request fails signature verification. In that case, the endpoint should reject the request with a 401 status code.

Referring domains

If an app is available in the Global region, requests arrive from the canva.com domain. If an app is available in the China region, requests arrive from the canva.cn domain.

The examples in this documentation assume requests are coming from canva.com. If you’re developing an app in China, replace references to canva.com with canva.cn.

Timeout duration

All HTTP requests that Canva sends to an app have a timeout duration. If the app fails to respond to the request within this duration, the request fails. The exact duration depends on the request.

If timeouts occur too frequently, Canva sends an automated message to the developer. If the timeouts aren’t solved within a reasonable time frame, Canva may disable the app.

Rate limiting

Canva sends requests to apps via a handful of IP addresses. If your endpoints support rate limiting — and they should — they may start to block the requests if their frequency passes a certain threshold. To handle this, whitelist requests from Canva's domains.

Signature verification

Before submitting an app for review, it must support signature verification. This is a security measure that prevents third-parties from sending requests to the app, which protects your app and Canva’s users from bad actors.

To learn more about signature verification, see Signature verification.