Skip to main content

HTTPS outcalls

Advanced
Network feature

Canisters can make a request to a URL using HTTPS outcalls. HTTPS outcalls can be used to directly obtain off-chain data or interact with off-chain systems, such as Web 2.0 services or enterprise IT infrastructure.

HTTPS outcalls enable a wide range of applications. For example, oracle services can directly integrate with ICP in a trustless manner, and dapps can provide user notifications or anything else that requires communication with servers on the Internet.

Some examples of onchain oracle-like services that obtain data from off-chain sources through HTTP outcalls include the EVM RPC canister, the exchange rate canister and the Orally dapp.

How it works​

The feature currently supports GET, HEAD, and POST methods for HTTP requests.

In order for a canister to use HTTPS outcalls, it needs to call the system API of ICP. Canisters can call into the system API by sending messages to the ICP management canister using the identifier "aaaaa-aa".

Cycles used to pay for the call must be explicitly transferred with the call. They are not deducted from the caller's balance implicitly.

For detailed information on how it works, please refer to the HTTPS outcalls reference documentation.

The API for sending HTTPS outcalls​

As per the Internet Computer interface specification, a canister can use the http_request method by following specification:

The request​

The following parameters should be supplied within the request:

  •   url: The requested URL that must be valid according to RFC-3986 and its length must not exceed 8192. The URL may specify a custom port number.

  •   max_response_bytes: Optional; specifies the maximal size of the response in bytes. If provided, the value must not exceed 2MB (2_000_000B). The call will be charged based on this parameter. If not provided, the maximum of 2MB will be used.

  •   method: Currently, only GET, HEAD, and POST are supported.

  •   headers: List of HTTP request headers and their corresponding values.

  •   body: Optional; The content of the request's body.

  •   transform: An optional function that transforms raw responses to sanitized responses, and a byte-encoded context that is provided to the function upon invocation, along with the response to be sanitized. If provided, the calling canister itself must export this function.

The response​

The returned response (and the response provided to the transform function, if specified) contains the following fields:

  •   status: The response status (e.g., 200, 404).

  •   headers: List of HTTP response headers and their corresponding values.

  •   body: The response's body.

Examples​

Refer to the following examples of HTTPS outcalls implementations in canisters: