Lifecycle Webhooks

What are Lifecycle Webhooks?

mittwald uses lifecycle webhooks to inform the external application of events relevant to that application. The extension defines the endpoints mittwald uses to send lifecycle updates in its configuration. The lifecycle updates are sent via a POST request.

Optionally, you can use different placeholders in the URLs used for the lifecycle webhooks. For more information on templating, see templating of configuration values. For an overview of the possible placeholders available in lifecycle webhook URL templates, see templating of webhook URLs.

Quality of Service (QoS) for the Delivery of Lifecycle Webhooks

The mStudio executes all webhook calls at least once. Therefore, you must design the webhook endpoints so that multiple calls do not result in errors. Every status code less than 200 or greater than or equal 300 is considered a failure. The webhook calls are executed asynchronously to the action that triggered them. If a webhook call fails, the webhook payload is rebuilt. The request is then signed and resubmitted. These retries are delayed with a capped exponential backoff to limit the number of requests.

The mStudio will retry a webhook call until it receives a response that the extension processed the call successfully. It also ensures that the webhooks are in the correct order per extension instance. The only exception to this rule is the removal of extensions from a context. In that case, the mStudio aborts all inactive or pending webhook calls. Only the ExtensionInstanceRemovedFromContext webhook call is executed and retried until the extension processes the call successfully or the extension is removed from the marketplace.

caution

If the mStudio backend does not receive a response from the extension webhook handler within 6 seconds, it interprets this as a timeout, and the webhook call execution fails. The mStudio retries the delivery of the webhook in this case as well. Therefore, you must ensure to design webhook call handlers to be idempotent. This avoids errors in scenarios where your webhook handler successfully processes a webhook call, but the response is not delivered to the mStudio backend in time.

In addition, we recommend that you do not synchronously execute complex computations or processes that could cause the webhook call processing to exceed the 6-second limit.

If the extension runs in a cloud environment, you should ensure not to completely scale down the webhook call handler. This leads to cold starts, which are included in the processing time from the perspective of the mStudio.

Secrets in Webhooks

The secrets that the mStudio communicates via webhook calls are valid as soon as the webhook call is processed successfully. You should expect an additional indefinite delay of less than a few seconds until the secret is valid. This is an additional reason to start initializing processes triggered by webhooks asynchronously and only process and store the transmitted data in the webhook handler.

For more information about how to use the extension instance secret, see authentication.

Primary Key / Identifier of Extension Instances

Every extension instance gets a unique extension instance ID. If you want to persist extension instances, you should use the extension instance ID as the primary key or unique identifier instead of the context ID. The following dangerous scenario that can occur due to the asynchronous nature of the webhook call executions is the reason for this recommendation. An extension is removed from a context and immediately added to the same context (for example, to start again with a clean configuration). If the ExtensionInstanceAddedToContext-webhook call of the new extension instance is processed before the ExtensionInstanceRemovedFromContext webhook of the old instance, this may lead to the deletion of all extension instances of that context. This includes the newly created extension instance that should exist.

Validation of Webhook Data

We do not recommend validating the data communicated by webhook calls and rejecting them in case of a validation error if this is not necessary for the execution of your extension. You should always see the mStudio as the single source of truth. If the format of extension instance IDs changes, for example, we will document and announce this. If you miss this information, the extension instance ID format validation presents an unnecessary risk.

Types of Lifecycle Webhooks

The following describes the semantic meaning of the different lifecycle webhooks. For more information for the request payloads, see the webhook reference.

ExtensionAddedToContext

This webhook communicates that an extension was added to a new context. During this process, the extension instance ID and the extension instance secret are transmitted for the first time.

You can't immediately use the extension instance secret in the webhook handler. The reason is described above in secrets in webhooks.

ExtensionInstanceUpdated

This webhook communicates a change in the state of the extension instance. It always includes the whole new state of the extension instance.

The activation and deactivation of the extension instance are an example of this.

ExtensionInstanceSecretRotated

The extension instance secret is rotated regularly for security reasons. This webhook communicates the new secret to the external application. The old secret is no longer valid at this point in time. You can't immediately use the new secret in the webhook handler, analogously to the ExtensionAddedToContext webhook. For more information, see secrets in webhooks.

ExtensionInstanceRemovedFromContext

This webhook communicates the removal of an extension instance from a context. You should ensure compliance with data privacy laws at this point and delete personal data for example.

note

We treat the ExtensionInstanceRemovedFromContext webhook differently regarding the QoS. It is possible to force remove the extension if the webhook handler is unreachable. In this case, we revoke all permissions of the extension instance and invalidate existing access tokens.

Nonetheless, the mStudio tries to execute the webhook to achieve a consistent state of the mStudio and extension data.

Verifying the Identity of the Sender of Webhooks

We provide the possibility to verify the identity of the sender and the integrity of the request body content. This way, you can ensure that the webhook call originated from mittwald. We include a signature and additional metadata about this signature in the request headers of webhooks.

This is important from the contributor's perspective because you can ensure that the webhook call originated from mittwald. Without such a webhook validation, there is a risk that a potential bad actor only needs to know the webhook URL to fake extension instances or corrupt existing ones. For more information about how to validate webhooks, see validation of lifecycle webhook reference.