docs(connectors): expand webhook verification expression documentation beyond one-time challenges

[Copilot]

Description

The verification expression documentation narrowly focused on one-time verification challenges (e.g., Slack URL verification), causing confusion about its broader applicability. Users need to understand this feature supports request validation, conditional responses, health checks, and early termination without process correlation.

Changes:

• Clarified scope: Expanded introduction listing 5 use cases beyond verification challenges
• Documented control flow: Added "How it works" section explaining null vs non-null behavior and interaction with webhook processing pipeline
• Standardized response format: Consolidated request/response patterns, explicitly documented default 200 status code
• Added practical examples:
  • Request validation returning 400 for missing required fields
  • Custom status codes (409 example demonstrating flexibility)
  • Custom headers (Content-Type override)
  • Nested body structure access
• Improved formatting: Converted inline code to proper FEEL/JSON code blocks with syntax highlighting
• Backported to versions 8.7 and 8.8: Applied the same documentation enhancements to previously released versions

Example usage:

=if request.body.requiredField = null
then {"body": {"error": "Missing required field"}, "statusCode": 400}
else null

Returns 400 and prevents correlation when validation fails; returns null to continue normal processing when valid.

Reference: camunda/connectors#5806

When should this change go live?

• This is already available but undocumented and should be released within a week. (add available & undocumented label)

PR Checklist

• The commit history of this PR is cleaned up, using {type}(scope): {description} commit message(s)

• My changes are for an upcoming minor release and are in the /docs directory (version 8.9).

• My changes are for an already released minor and are in a /versioned_docs directory.

• I added a DRI, team, or delegate as a reviewer for technical accuracy and grammar/style:

  • Engineering team review
  • Technical writer review via @camunda/tech-writers unless working with an embedded writer.

Original prompt

Problem

The current documentation for the Webhook Connector's verification expression in docs/components/connectors/protocol/http-webhook.md focuses exclusively on the one-time challenge use case. However, verification expressions can be used for a broader range of scenarios where users need more control over the response returned by the connector.

This has caused confusion for some users, who may not realize that the feature is applicable beyond the one-time verification challenge.

Reference issue: camunda/connectors#5806

Current State

The current "Verification expression" section (starting around line 271) only describes:

• One-time verification challenge use case (e.g., Slack URL verification)
• Basic request/response placeholders

Requested Improvements

1. Expand the introduction to clearly describe that verification expressions can be used for multiple scenarios beyond one-time challenges, including:

   • Customizing responses based on payload content
   • Validating incoming requests before creating a process instance
   • Returning early responses without triggering process correlation
   • Health check endpoints

2. Add concrete examples demonstrating broader use cases:

   • Request validation example: Reject requests with invalid payloads by returning 400/422 status codes
   • Conditional response example: Return different responses based on request content
   • Custom headers example: Return responses with custom headers (e.g., Content-Type: application/camunda-bin)

3. Clarify how verification expressions interact with standard webhook configuration:

   • Explain that when a verification expression returns a non-null response, the webhook returns immediately WITHOUT triggering process correlation
   • When the expression returns null, the request proceeds through normal webhook processing (activation condition, HMAC validation, etc.)

4. Document HTTP status code behavior:

   • Default status code is 200 if not specified
   • How to return error codes (400, 422, etc.) for validation failures
   • Clarify that users can override any status code

Files to Update

The main file to update is: docs/components/connectors/protocol/http-webhook.md

The verification expression section starts around line 271 with ### Verification expression.

Example Content to Add

Here are example verification expressions from the connector test suite that should be documented:

Request Validation Example

=if request.body.requiredField = null then 
  {"body": {"error": "Missing required field"}, "statusCode": 400} 
else null

Custom Status Code Example

=if request.body.challenge != null then 
  {"body": {"challenge": request.body.challenge}, "statusCode": 409} 
else null

Custom Headers Example

=if request.body.challenge != null then 
  {"body": {"challenge": request.body.challenge}, "headers": {"Content-Type": "application/camunda-bin"}} 
else null

Nested Body Structure Example

=if request.body.event_type = "verification" then 
  {"body": {"challenge": request.body.event.challenge}} 
else null

Notes

• Keep the existing Slack verification example as it's a valid use case
• Add the new examples and explanations to expand the scope of the documentation
• Ensure the documentation makes clear that returning null means "continue with normal processing" while returning a response object means "respond immediately without triggering correlation"

This pull request was created as a result of the following prompt from Copilot chat.

Problem

The current documentation for the Webhook Connector's verification expression in docs/components/connectors/protocol/http-webhook.md focuses exclusively on the one-time challenge use case. However, verification expressions can be used for a broader range of scenarios where users need more control over the response returned by the connector.

This has caused confusion for some users, who may not realize that the feature is applicable beyond the one-time verification challenge.

Reference issue: camunda/connectors#5806

Current State

The current "Verification expression" section (starting around line 271) only describes:

• One-time verification challenge use case (e.g., Slack URL verification)
• Basic request/response placeholders

Requested Improvements

1. Expand the introduction to clearly describe that verification expressions can be used for multiple scenarios beyond one-time challenges, including:

   • Customizing responses based on payload content
   • Validating incoming requests before creating a process instance
   • Returning early responses without triggering process correlation
   • Health check endpoints

2. Add concrete examples demonstrating broader use cases:

   • Request validation example: Reject requests with invalid payloads by returning 400/422 status codes
   • Conditional response example: Return different responses based on request content
   • Custom headers example: Return responses with custom headers (e.g., Content-Type: application/camunda-bin)

3. Clarify how verification expressions interact with standard webhook configuration:

   • Explain that when a verification expression returns a non-null response, the webhook returns immediately WITHOUT triggering process correlation
   • When the expression returns null, the request proceeds through normal webhook processing (activation condition, HMAC validation, etc.)

4. Document HTTP status code behavior:

   • Default status code is 200 if not specified
   • How to return error codes (400, 422, etc.) for validation failures
   • Clarify that users can override any status code

Files to Update

The main file to update is: docs/components/connectors/protocol/http-webhook.md

The verification expression section starts around line 271 with ### Verification expression.

Example Content to Add

Here are example verification expressions from the connector test suite that should be documented:

Request Validation Example

=if request.body.requiredField = null then 
  {"body": {"error": "Missing required field"}, "statusCode": 400} 
else null

Custom Status Code Example

=if request.body.challenge != null then 
  {"body": {"challenge": request.body.challenge}, "statusCode": 409} 
else null

Custom Headers Example

=if request.body.challenge != null then 
  {"body": {"challenge": request.body.challenge}, "headers": {"Content-Type": "application/camunda-bin"}} 
else null

Nested Body Structure Example

=if request.body.event_type = "verification" then 
  {"body": {"challenge": request.body.event.challenge}} 
else null

Notes

• Keep the existing Slack verification example as it's a valid use case
• Add the new examples and explanations to expand the scope of the documentation
• Ensure the documentation makes clear that returning null means "continue with normal processing" while returning a response object means "respond immediately without triggering correlation"

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[johnBgood]

@copilot add the same change to the versioned_docs folder, for 8.8 and 8.7

[Copilot]

@copilot add the same change to the versioned_docs folder, for 8.8 and 8.7

Applied the same verification expression documentation enhancements to versions 8.7 and 8.8 in commit 7157f7a.