Workflow Webhook

Workflow Webhook is a workflow type that defines processes triggered by webhooks. It allows external systems to trigger workflows via HTTP requests.

Trigger

Webhook workflows are triggered via the following endpoint:

POST /api/v2/orgs/{organizationId}/webhooks/{workflowId}

Protection

By default, webhook workflows do not have protection. However, it is recommended to use protection to ensure security.

The recommended protection tasks:

• Utilities/ValidateHMAC@1: Validates webhook requests using HMAC.
• Utilities/ValidateReCaptcha@1: Validates webhook requests using ReCaptcha.

Inputs

Workflow Webhook has the following inputs:

• payload: The payload object of the webhook request.
• request: The request object. Http request object.
  • headers - Http request headers.
  • body - Http request body.

Outputs

Workflow Webhook has the following outputs:

• status: The status of the webhook processing. Optional.
• response: The response from the webhook processing. Optional.

Example

workflow:
  name: "Webhooks / Example"
  description: "Webhooks / Example"
  workflowId: "64ea14ab-ed3f-410f-9dd7-43c726203f40"
  isActive: true
  workflowType: "Webhook"
  executionMode: "Async"
  runAs: "system" # Run the workflow as the system user
  version: "1.0"
  additionalProperties:
    cors: # CORS configuration
      allowedOrigins:
        - "https://example.com"

inputs:
  - name: "payload"
    type: "object"
  - name: "request"
    type: "object"

variables:
  - name: "workflowSecret"
    fromConfig:
      configName: "auth.config"
      key: "workflowSecret"
  - name: "captchaSecret"
    fromConfig:
      configName: "auth.config"
      key: "captchaSecret"

outputs:
  - name: "statusCode"
    mapping: "processWebhook?.statusCode" # Status of the webhook processing
  - name: "response"
    mapping: "processWebhook?.message" # Message associated with the webhook processing

activities:
  - name: authenticate # Authenticate the webhook request
    steps:
      - task: "Utilities/ValidateHMAC@1"
        name: "validateHMAC"
        inputs:
          secret: "{{ workflowSecret? }}"
          algorithm: "SHA256"
          signature: "{{ request.headers['X-Hub-Signature']? }}"
          payload: "{{ request?.body }}" # Request payload is a text value
          throwException: false
        outputs:
          - name: "isValid"
            mapping: "validation.isValid"

      - task: "Utilities/ValidateReCaptcha@1" # Validate the captcha
        name: "validateCaptcha"
        inputs:
          secret: "{{ captchaSecret? }}"
          token: "{{ request.headers['X-CaptchaToken']? }}"
          version: 3
          throwException: false
        outputs:
          - name: "isValid"
            mapping: "validation.isValid"

  - name: processWebhook
    steps:
      - task: "ActionEvent/Create@1"
        name: "createActionEvent"
        inputs:
          action:
            eventName: "webhook.example"
            eventData:
              payload: "{{ payload }}"