Developer Guide

Invoking Extensions

This section explains what your platform needs to do in order to invoke extension logic.

In all instances, invocation of an extension occurs during an operation or transaction which makes the following parameters implicit:

  • {webtask_container}: the name of the webtask container associated with the current isolation scope (e.g. tenant) as determined in Mapping Isolation Requirements onto Webtask Tokens. For example, if your system isolates each tenant’s extensions and you need to invoke one on their behalf, then {webtask_container} will be the name of that tenant’s webtask container.

  • {extensibility_point_name}: a unique name of the extensibility point you want to invoke, e.g. “on-new-lead”.

With this information, you can discover if an extension is defined for a given extensibility point and isolation scope. The discovery process leads to the determination of the following two parameters, both of which are necessary to invoke the extension:

  • {host_url}: this is the url to the specific extension instance to call.

  • {extension_secret}: this is the value of the auth0-extension-secret metadata property you will need to authorize the call.

NOTE invoking the discovery logic every time you need to execute an extension in your system may be impractical from a performance perspective, depending on the frequency of extension execution. Consider applying a caching mechanism to reduce the overhead of repeated Extend management API calls related to discovery.

In addition to the parameters above, you need a payload to supply to the extension, which you defined as part of identifying the extensibility points in your platform.

Extend supports creating extensions that leverage the full flexibility of HTTP, including support for different verbs and content types. In the most common case of using JSON to submit payload to the extension, an invocation of the extension would look like this:

POST {host_url}
Content-Type: application/json
Authorization: Bearer {extension_secret}

{payload}

A typical success response would have an HTTP 200 status code and contain a JSON response body generated by the extension code. Your platform is responsible for performing any necessary validation of the status code and payload.

See invokeExtension function from a sample Extend application.

The errors you may receive from calling Extend extensions fall into several categories and are described in Handling Errors from Extensions.

One of the implementation decisions you need to make when invoking extensions is related to their synchronous or asynchronous semantics, which you determined when identifying the extensibility points in your platform.

When invoking synchronous extensions, your platform depends on the completion (and possibly the response data) of the extension. This means that your code must wait for the HTTPS request to complete before it can continue processing. In such cases, you should consider enforcing a timeout on the overall duration of extension execution in order to ensure your users have a good experience.

When invoking asynchronous extensions, transaction processing in your platform will continue as soon as the HTTPS request to the invoke the extension has been issued. One consideration you should make in this case is related to the handling of errors and output from asynchronous extensions. To aid in troubleshooting and monitoring, it may be reasonable to capture and log the outcome of asynchronous extension execution, even though it does not affect the processing of the transaction that triggered it.