Update header references in generic webhook to be lowercase

Update note about known issues in header names in generic webhook
port-labs · Feb 24, 2025 · 673775e · 673775e
1 parent c7c02d3
commit 673775e
Show file tree

Hide file tree

Showing 10 changed files with 37 additions and 36 deletions.
diff --git a/docs/actions-and-automations/setup-backend/azure-pipeline/azure-pipeline.md b/docs/actions-and-automations/setup-backend/azure-pipeline/azure-pipeline.md
@@ -8,7 +8,7 @@ The Azure backend can trigger [Azure pipelines](https://azure.microsoft.com/en-u
 The steps shown in the image above are as follows:
 
 1. A self-service action or automation is invoked in Port.
-2. Port signs the action payload using SHA-1 with your Port [`clientSecret`](/build-your-software-catalog/custom-integration/api/api.md#find-your-port-credentials) value and puts it in the `X-Port-Signature` request header.
+2. Port signs the action payload using SHA-1 with your Port [`clientSecret`](/build-your-software-catalog/custom-integration/api/api.md#find-your-port-credentials) value and puts it in the `x-port-signature` request header.
 
    :::info Webhook security
    Verifying the webhook request using the request headers provides the following benefits:
@@ -41,7 +41,7 @@ To define an incoming webhook in Azure, follow the steps below:
         - **Webhook Name**: The webhook name e.g. "port_trigger"
         - **Service connection name**: The name of the service connection (e.g., "port_trigger").
         - **Secret key**: Enter your Port `clientSecret` value.
-        - **Headers**: Type in `X-Port-Signature`.
+        - **Headers**: Type in `x-port-signature`.
     - Check `Grant access to all pipelines`
     - Click `Save`.
 

diff --git a/docs/actions-and-automations/setup-backend/jenkins-pipeline/jenkins-pipeline.md b/docs/actions-and-automations/setup-backend/jenkins-pipeline/jenkins-pipeline.md
@@ -10,7 +10,7 @@ The Jenkins backend allows you to trigger Jenkins pipelines for your self-servic
 The steps shown in the image above are as follows:
 
 1. A self-service action or automation is invoked in Port.
-2. Port signs the action payload using SHA-1 with your Port [`clientSecret`](/build-your-software-catalog/custom-integration/api/api.md#find-your-port-credentials) value and puts it in the `X-Port-Signature` request header.
+2. Port signs the action payload using SHA-1 with your Port [`clientSecret`](/build-your-software-catalog/custom-integration/api/api.md#find-your-port-credentials) value and puts it in the `x-port-signature` request header.
 
    :::info Webhook security
    Verifying the webhook request using the request headers provides the following benefits:

diff --git a/.../build-your-software-catalog/custom-integration/webhook/examples/git/_github.md b/.../build-your-software-catalog/custom-integration/webhook/examples/git/_github.md
@@ -37,10 +37,10 @@ Create the following webhook configuration [using Port's UI](/build-your-softwar
 3. Scroll down to **Advanced settings** and input the following details:
 
    1. Secret: `WEBHOOK_SECRET`;
-   2. Signature Header Name : `X-Hub-Signature-256`;
+   2. Signature Header Name : `x-hub-signature-256`;
    3. Signature Algorithm : Select `sha256` from dropdown option;
    4. Signature Prefix : `sha256=`;
-   5. Request Identifier Path : `.headers.\"X-GitHub-Delivery\"`;
+   5. Request Identifier Path : `.headers.\"x-github-delivery\"`;
    6. Click **Save** at the bottom of the page.
 
 </details>

diff --git a/.../build-your-software-catalog/custom-integration/webhook/examples/git/_gitlab.md b/.../build-your-software-catalog/custom-integration/webhook/examples/git/_gitlab.md
@@ -37,7 +37,7 @@ Create the following webhook configuration [using Port's UI](/build-your-softwar
    <MergeRequestWebhookConfig/>
 
 3. Scroll down to **Advanced settings** and input the following details:
-   1. Request Identifier Path : `.headers.X-Gitlab-Event-Uuid`;
+   1. Request Identifier Path : `.headers.x-gitlab-event-uuid`;
    2. Click **Save** at the bottom of the page.
 
 </details>

diff --git a/...ebhook/examples/resources/bitbucket-server/_example_bitbucket_python_script.mdx b/...ebhook/examples/resources/bitbucket-server/_example_bitbucket_python_script.mdx
@@ -154,10 +154,10 @@ async def create_port_webhook():
         "enabled": True,
         "security": {
             "secret": WEBHOOK_SECRET,
-            "signatureHeaderName": "X-Hub-Signature",
+            "signatureHeaderName": "x-hub-signature",
             "signatureAlgorithm": "sha256",
             "signaturePrefix": "sha256=",
-            "requestIdentifierPath": ".headers['X-Request-ID']",
+            "requestIdentifierPath": ".headers['x-request-id']",
         },
         "integrationType": "custom",
     }

diff --git a/...-integration/webhook/examples/resources/general/_example_full_configuration.mdx b/...-integration/webhook/examples/resources/general/_example_full_configuration.mdx
@@ -8,7 +8,7 @@
   "mappings": [
     {
       "blueprint": "pullRequest",
-      "filter": ".headers.\"X-GitHub-Event\" == \"pull_request\"",
+      "filter": ".headers.\"x-github-event\" == \"pull_request\"",
       "entity": {
         "identifier": ".body.pull_request.id | tostring",
         "title": ".body.pull_request.title",

diff --git a/...egration/webhook/examples/resources/github/_example_github_pr_configuration.mdx b/...egration/webhook/examples/resources/github/_example_github_pr_configuration.mdx
@@ -2,7 +2,7 @@
 [
   {
     "blueprint": "pullRequest",
-    "filter": ".headers.\"X-GitHub-Event\" == \"pull_request\"",
+    "filter": ".headers.\"x-github-event\" == \"pull_request\"",
     "entity": {
       "identifier": ".body.pull_request.id | tostring",
       "title": ".body.pull_request.title",

diff --git a/docs/build-your-software-catalog/custom-integration/webhook/examples/stackhawk.md b/docs/build-your-software-catalog/custom-integration/webhook/examples/stackhawk.md
@@ -40,7 +40,7 @@ Remember to update the `WEBHOOK_SECRET` and `AUTH_SIGNATURE_HEADER` with the rea
    3. `Scan Data For` - choose the application(s) you want to receive webhook events for or choose `Select All` if you want to configure a global webhook for all your applications.
    4. `Scan Events` - choose `Scan Completed` event type.
    5. `Webhook Endpoint URL` - enter the value of the `url` key you received after [creating the webhook configuration](/build-your-software-catalog/custom-integration/webhook#configuring-webhook-endpoints).
-   6. `Auth Header Name` - enter the name of the HTTP header that will contain your auth token/key. For example, you can enter `X-StackHawk-Port-Webhook`.
+   6. `Auth Header Name` - enter the name of the HTTP header that will contain your auth token/key. For example, you can enter `x-stackhawk-port-webhook`.
    7. `Auth Header Value` - enter the secret authentication token that will be added to your webhook payload.
 4. Click **Create and Test** to create your webhook.
 

diff --git a/docs/build-your-software-catalog/custom-integration/webhook/webhook.md b/docs/build-your-software-catalog/custom-integration/webhook/webhook.md
@@ -164,7 +164,7 @@ Below is an example of a mapping configuration:
     {
       "blueprint": "pullRequest",
       "operation": "create",
-      "filter": ".headers.\"X-GitHub-Event\" == \"pull_request\"",
+      "filter": ".headers.\"x-github-event\" == \"pull_request\"",
       "entity": {
         "identifier": ".body.pull_request.id | tostring",
         "title": ".body.pull_request.title",
@@ -197,7 +197,7 @@ Below is an example of a mapping configuration:
       {
         blueprint = "pullRequest"
         operation = "create"
-        filter = ".headers.\"X-GitHub-Event\" == \"pull_request\""
+        filter = ".headers.\"x-github-event\" == \"pull_request\""
         entity = {
           identifier = ".body.pull_request.id | tostring"
           title = ".body.pull_request.title"
@@ -230,7 +230,8 @@ When configuring the mapping, the following keys are available for use in the JQ
 | `.item`        | A reference to items in the array specified in `itemsToParse`. Will be available in the JQ context if `itemsToParse` is used. |
 
 :::warning Known issues
-As the webhook custom integration is receiving the requests from AWS API Gateway, there are some issues that might affect the value of the fields in one of the context keys. For example, the `headers` key might not have the expected casing.
+As the webhook custom integration is receiving the requests from AWS API Gateway, there are some issues that might affect the value of the fields in one of the context keys. For example, the keys in the `headers` object might not have the expected casing, we recommend that you always reference keys from the `headers` object using lowercase versions of the header names (for example - `x-port-signature`).
+
 Please refer to the [AWS API Gateway known issues](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-known-issues.html#api-gateway-known-issues-rest-apis) for more information.
 :::
 
@@ -264,7 +265,7 @@ Now let's explore the structure of a single mapping object:
     {
       // highlight-next-line
       "blueprint": "pullRequest",
-      "filter": ".headers.\"X-GitHub-Event\" == \"pull_request\"",
+      "filter": ".headers.\"x-github-event\" == \"pull_request\"",
       ...
     }
   ]
@@ -308,7 +309,7 @@ Now let's explore the structure of a single mapping object:
     {
       "blueprint": "pullRequest",
       // highlight-next-line
-      "filter": ".headers.\"X-GitHub-Event\" == \"pull_request\"" # JQ boolean query. If evaluated to false - skip the payload.
+      "filter": ".headers.\"x-github-event\" == \"pull_request\"" # JQ boolean query. If evaluated to false - skip the payload.
       ...
     }
   ]
@@ -359,7 +360,7 @@ Now let's explore the structure of a single mapping object:
   "mappings": [
     {
       ...
-      "filter": ".headers.\"X-GitHub-Event\" == \"pull_request\"",
+      "filter": ".headers.\"x-github-event\" == \"pull_request\"",
       // highlight-start
       "entity": {
         "identifier": ".body.pull_request.id | tostring",
@@ -447,10 +448,10 @@ Here is an example security configuration:
   // highlight-start
   "security": {
     "secret": "WEBHOOK_SECRET",
-    "signatureHeaderName": "X-Hub-Signature-256",
+    "signatureHeaderName": "x-hub-signature-256",
     "signatureAlgorithm": "sha256",
     "signaturePrefix": "sha256=",
-    "requestIdentifierPath": ".headers.\"X-GitHub-Delivery\""
+    "requestIdentifierPath": ".headers.\"x-github-delivery\""
   }
   // highlight-end
 }
@@ -471,10 +472,10 @@ resource "port_webhook" "myWebhook" {
     // highlight-start
     security = {
       secret = "WEBHOOK_SECRET"
-      signature_header_name = "X-Hub-Signature-256"
+      signature_header_name = "x-hub-signature-256"
       signature_algorithm = "sha256"
       signature_prefix = "sha256="
-      request_identifier_path = ".headers.\"X-GitHub-Delivery\""
+      request_identifier_path = ".headers.\"x-github-delivery\""
     }
     // highlight-end
 }
@@ -501,10 +502,10 @@ If you do not want to supply a security configuration with your webhook configur
   // highlight-next-line
   "security": {
     "secret": "WEBHOOK_SECRET",
-    "signatureHeaderName": "X-Hub-Signature-256",
+    "signatureHeaderName": "x-hub-signature-256",
     "signatureAlgorithm": "sha256",
     "signaturePrefix": "sha256=",
-    "requestIdentifierPath": ".headers.\"X-GitHub-Delivery\""
+    "requestIdentifierPath": ".headers.\"x-github-delivery\""
   }
   ...
 }
@@ -518,10 +519,10 @@ If you do not want to supply a security configuration with your webhook configur
   "security": {
     // highlight-next-line
     "secret": "WEBHOOK_SECRET",
-    "signatureHeaderName": "X-Hub-Signature-256",
+    "signatureHeaderName": "x-hub-signature-256",
     "signatureAlgorithm": "sha256",
     "signaturePrefix": "sha256=",
-    "requestIdentifierPath": ".headers.\"X-GitHub-Delivery\""
+    "requestIdentifierPath": ".headers.\"x-github-delivery\""
   }
   ...
 }
@@ -535,10 +536,10 @@ If you do not want to supply a security configuration with your webhook configur
   "security": {
     "secret": "WEBHOOK_SECRET",
     // highlight-next-line
-    "signatureHeaderName": "X-Hub-Signature-256",
+    "signatureHeaderName": "x-hub-signature-256",
     "signatureAlgorithm": "sha256",
     "signaturePrefix": "sha256=",
-    "requestIdentifierPath": ".headers.\"X-GitHub-Delivery\""
+    "requestIdentifierPath": ".headers.\"x-github-delivery\""
   }
   ...
 }
@@ -552,11 +553,11 @@ If you do not want to supply a security configuration with your webhook configur
   ...
   "security": {
     "secret": "WEBHOOK_SECRET",
-    "signatureHeaderName": "X-Hub-Signature-256",
+    "signatureHeaderName": "x-hub-signature-256",
     // highlight-next-line
     "signatureAlgorithm": "sha256",
     "signaturePrefix": "sha256=",
-    "requestIdentifierPath": ".headers.\"X-GitHub-Delivery\""
+    "requestIdentifierPath": ".headers.\"x-github-delivery\""
   }
   ...
 }
@@ -573,29 +574,29 @@ When using the `plain` algorithm, no hashing will be performed and the value of
   ...
   "security": {
     "secret": "WEBHOOK_SECRET",
-    "signatureHeaderName": "X-Hub-Signature-256",
+    "signatureHeaderName": "x-hub-signature-256",
     "signatureAlgorithm": "sha256",
     // highlight-next-line
     "signaturePrefix": "sha256=",
-    "requestIdentifierPath": ".headers.\"X-GitHub-Delivery\""
+    "requestIdentifierPath": ".headers.\"x-github-delivery\""
   }
   ...
 }
 ```
 
 - The `requestIdentifierPath` key is used to specify a JQ pattern resulting in a unique identifier of the webhook payload:
   - This key is used to prevent Port from processing an event more than once;
-  - For example, in GitHub webhooks, the `X-GitHub-Delivery` header contains a GUID used to identify the delivery. So the webhook should be configured with: `"requestIdentifierPath": ".headers.\"X-GitHub-Delivery\""`;
+  - For example, in GitHub webhooks, the `x-github-delivery` header contains a GUID used to identify the delivery. So the webhook should be configured with: `"requestIdentifierPath": ".headers.\"x-github-delivery\""`;
 
 ```json showLineNumbers
   ...
   "security": {
     "secret": "WEBHOOK_SECRET",
-    "signatureHeaderName": "X-Hub-Signature-256",
+    "signatureHeaderName": "x-hub-signature-256",
     "signatureAlgorithm": "sha256",
     "signaturePrefix": "sha256=",
     // highlight-next-line
-    "requestIdentifierPath": ".headers.\"X-GitHub-Delivery\""
+    "requestIdentifierPath": ".headers.\"x-github-delivery\""
   }
   ...
 }

diff --git a/...oftware-catalog/sync-data-to-catalog/incident-management/pagerduty/pagerduty.md b/...oftware-catalog/sync-data-to-catalog/incident-management/pagerduty/pagerduty.md
@@ -1193,7 +1193,7 @@ Create the following webhook configuration [using Port UI](/build-your-software-
 3. Scroll down to **Advanced settings** and input the following details:
 
    1. secret: `WEBHOOK_SECRET`;
-   2. Signature Header Name : `X-Pagerduty-Signature`;
+   2. Signature Header Name : `x-pagerduty-signature`;
    3. Signature Algorithm : Select `sha256` from dropdown option;
    4. Signature Prefix : `v1=`
    5. Click **Save** at the bottom of the page.
@@ -1387,7 +1387,7 @@ Create the following webhook configuration [using Port UI](/build-your-software-
 
 3. Scroll down to **Advanced settings** and input the following details:
    1. secret: `WEBHOOK_SECRET`;
-   2. Signature Header Name : `X-Pagerduty-Signature`;
+   2. Signature Header Name : `x-pagerduty-signature`;
    3. Signature Algorithm : Select `sha256` from dropdown option;
    4. Signature Prefix : `v1=`
    5. Click **Save** at the bottom of the page.