Merge pull request #115 from mittwald/docs/webhook-verification-php

Document how to do webhook verification in PHP
mittwald · Sep 26, 2024 · 8d6c31b · 8d6c31b
2 parents 7fa00a4 + 2aca426
commit 8d6c31b
Show file tree

Hide file tree

Showing 2 changed files with 60 additions and 4 deletions.
diff --git a/docs/contribution/6-reference/4-webhooks.mdx b/docs/contribution/6-reference/4-webhooks.mdx
@@ -1,8 +1,11 @@
 ---
 title: Lifecycle Webhooks
 ---
+
 import OperationLink from "@site/src/components/OperationLink";
 import SchemaWithExample from "../../../src/components/openapi/SchemaWithExample";
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
 
 mittwald uses lifecycle events to notify the the external application of events that concern it.
 
@@ -544,6 +547,9 @@ You can use common cryptographic libraries in your preferred programming languag
 The complete and unprocessed request body has to be verified using the `verify` method.
 This ensures that the request body was transmitted by mittwald and was not modified by a third party.
 
+<Tabs>
+  <TabItem value="go" label="Go">
+
 ```go
 bodyBytes, err := io.ReadAll(body)
 if err != nil {
@@ -555,6 +561,28 @@ if !ed25519.Verify(publicKey, bodyBytes, signature) {
 }
 ```
 
+  </TabItem>
+  <TabItem value="php" label="PHP">
+
+```php
+$req  = new ExtensionGetPublicKeyRequest($serial);
+$resp = $apiClient->marketplace()->extensionGetPublicKey($req);
+$key = $resp->getBody()->getKey();
+
+$valid = sodium_crypto_sign_verify_detached(
+    base64_decode($signature),
+    $request->getContent(),
+    base64_decode($key),
+);
+
+if (!$valid) {
+    throw new \Exception('invalid request signature');
+}
+```
+
+  </TabItem>
+</Tabs>
+
 ### Reference Implementations of the Validation of Lifecycle Webhooks
 
 TODO
diff --git a/.../docusaurus-plugin-content-docs/current/contribution/6-reference/4-webhooks.mdx b/.../docusaurus-plugin-content-docs/current/contribution/6-reference/4-webhooks.mdx
@@ -1,8 +1,11 @@
 ---
 title: Lifecycle Webhooks
 ---
+
 import OperationLink from "@site/src/components/OperationLink";
 import SchemaWithExample from "../../../../../../src/components/openapi/SchemaWithExample";
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
 
 Lifecycle Events werden von mittwald genutzt, um die externe Anwendung über sie betreffende Ereignisse zu informieren.
 
@@ -538,16 +541,41 @@ Algorithmus, der zum Erzeugen der Signatur verwendet wurde, derzeit immer [`Ed25
 
 Um die Signatur zu prüfen, kann eine übliche kryptographische Library in der gewählten Programmiersprache verwendet werden. Dazu wird mithilfe der `verify`-Methode der gesamte, unverarbeitete Request Body geprüft. Damit ist sichergestellt, dass der übermittelte Request Body unmodifiziert von mittwald übertragen wurde.
 
-```go
+<Tabs>
+  <TabItem value="go" label="Go">
+
+````go
 bodyBytes, err := io.ReadAll(body)
 if err != nil {
-   return err
+  return err
 }
 
 if !ed25519.Verify(publicKey, bodyBytes, signature) {
-   panic("invalid signature")
+  panic("invalid signature")
 }
-```
+    ```
+
+  </TabItem>
+  <TabItem value="php" label="PHP">
+
+```php
+$req  = new ExtensionGetPublicKeyRequest($serial);
+$resp = $apiClient->marketplace()->extensionGetPublicKey($req);
+$key = $resp->getBody()->getKey();
+
+$valid = sodium_crypto_sign_verify_detached(
+    base64_decode($signature),
+    $request->getContent(),
+    base64_decode($key),
+);
+
+if (!$valid) {
+    throw new \Exception('invalid request signature');
+}
+````
+
+  </TabItem>
+</Tabs>
 
 ### Referenzimplementierungen für die Validierung von Lifecycle Webhooks