diff --git a/docs/contribution/5-reference/4-webhooks.mdx b/docs/contribution/5-reference/4-webhooks.mdx index 26e7e7d5..e43c9844 100644 --- a/docs/contribution/5-reference/4-webhooks.mdx +++ b/docs/contribution/5-reference/4-webhooks.mdx @@ -91,10 +91,7 @@ You may use the following placeholders: }, meta: { type: "object", - required: [ - "extensionId", - "contributorId" - ], + required: ["extensionId", "contributorId"], properties: { extensionId: { type: "string", @@ -212,10 +209,7 @@ You may use the following placeholders: }, meta: { type: "object", - required: [ - "extensionId", - "contributorId" - ], + required: ["extensionId", "contributorId"], properties: { extensionId: { type: "string", @@ -271,7 +265,15 @@ You may use the following placeholders: format="yaml" schema={{ type: "object", - required: ["apiVersion", "context", "kind", "id", "secret", "request"], + required: [ + "apiVersion", + "context", + "kind", + "id", + "meta", + "secret", + "request", + ], properties: { apiVersion: { type: "string", @@ -300,6 +302,22 @@ You may use the following placeholders: }, }, }, + meta: { + type: "object", + required: ["extensionId", "contributorId"], + properties: { + extensionId: { + type: "string", + format: "uuid", + example: "c593348d-f594-492a-8185-2b89848a4160", + }, + contributorId: { + type: "string", + format: "uuid", + example: "680ba069-7465-4932-8b23-e73914b2e051", + }, + }, + }, secret: { type: "string", example: "ROFLieg83rjfdoi9lLIifdlfi399fndLKFHj39fjdlr", @@ -404,10 +422,7 @@ You may use the following placeholders: }, meta: { type: "object", - required: [ - "extensionId", - "contributorId" - ], + required: ["extensionId", "contributorId"], properties: { extensionId: { type: "string", @@ -515,9 +530,12 @@ In that case, domain actions of that extension instance are not accepted. ### meta -Meta information about the extension instance. -Currently, the mStudio only sends the creation date of the extension instance. -This should not be confused with the request meta information which describes the webhook call. +Meta information about the extension (instance). +This includes the extensionID and the contributorID. + +These information should be used to ensure that the webhook not only originates from mittwald, but is also intended for the own extension. +This prevents forward replay attacks. +This should not be confused with the request meta information which describes the webhook call itself. ### secret @@ -659,8 +677,8 @@ If the values are not set, the mStudio derives them from the extension or genera }, secret: { type: "string", - example: "<>" - } + example: "<>", + }, }, }} /> diff --git a/i18n/de/docusaurus-plugin-content-docs/current/contribution/5-reference/4-webhooks.mdx b/i18n/de/docusaurus-plugin-content-docs/current/contribution/5-reference/4-webhooks.mdx index 9be53653..31ab7b0a 100644 --- a/i18n/de/docusaurus-plugin-content-docs/current/contribution/5-reference/4-webhooks.mdx +++ b/i18n/de/docusaurus-plugin-content-docs/current/contribution/5-reference/4-webhooks.mdx @@ -91,10 +91,7 @@ Folgende Platzhalter können verwendet werden: }, meta: { type: "object", - required: [ - "extensionId", - "contributorId" - ], + required: ["extensionId", "contributorId"], properties: { extensionId: { type: "string", @@ -212,10 +209,7 @@ Folgende Platzhalter können verwendet werden: }, meta: { type: "object", - required: [ - "extensionId", - "contributorId" - ], + required: ["extensionId", "contributorId"], properties: { extensionId: { type: "string", @@ -271,7 +265,15 @@ Folgende Platzhalter können verwendet werden: format="yaml" schema={{ type: "object", - required: ["apiVersion", "context", "kind", "id", "secret", "request"], + required: [ + "apiVersion", + "context", + "kind", + "id", + "meta", + "secret", + "request", + ], properties: { apiVersion: { type: "string", @@ -300,6 +302,22 @@ Folgende Platzhalter können verwendet werden: }, }, }, + meta: { + type: "object", + required: ["extensionId", "contributorId"], + properties: { + extensionId: { + type: "string", + format: "uuid", + example: "c593348d-f594-492a-8185-2b89848a4160", + }, + contributorId: { + type: "string", + format: "uuid", + example: "680ba069-7465-4932-8b23-e73914b2e051", + }, + }, + }, secret: { type: "string", example: "ROFLieg83rjfdoi9lLIifdlfi399fndLKFHj39fjdlr", @@ -404,10 +422,7 @@ Folgende Platzhalter können verwendet werden: }, meta: { type: "object", - required: [ - "extensionId", - "contributorId" - ], + required: ["extensionId", "contributorId"], properties: { extensionId: { type: "string", @@ -516,7 +531,12 @@ Somit würden auch Domain Actions für eine deaktivierte Extension Instance nich ### meta -Meta-Informationen über die Extension Instance. Derzeit wird lediglich der Erstellungszeitpunkt der Extension Instance übermittelt. +Meta-Informationen über die Extension (Instance). +Diese beinhalten die IDs der Extension und des Contributors. + +Diese Informationen sollten bspw. verwendet werden, um sicherzustellen, dass der Webhook nicht nur ursprünglich von mittwald stammt, +sondern auch für die eigene Extension bestimmt ist. +Dies beugt Forward-Replay-Attacken vor. Dies ist nicht zu verwechseln mit den Request Meta Informationen, die Aufschluss über den Webhook an sich geben. ### secret @@ -576,7 +596,8 @@ if err != nil { if !ed25519.Verify(publicKey, bodyBytes, signature) { panic("invalid signature") } -``` + +```` ```php @@ -593,7 +614,8 @@ $valid = sodium_crypto_sign_verify_detached( if (!$valid) { throw new \Exception('invalid request signature'); } -``` +```` + @@ -649,8 +671,8 @@ Sind diese Werte nicht gesetzt, werden sie aus der Extension abgeleitet oder zuf }, secret: { type: "string", - example: "<>" - } + example: "<>", + }, }, }} />