version: 2.1

description: A simple orb to send fully-customized Slack messages via Slack webhooks.

display:
  source_url: https://github.com/adamu/slack-webhook-orb

commands:
  send-message:
    description: Send a message to slack via a webhook.
    parameters:
      json-payload:
        type: string
        description: The Slack JSON Payload.
      webhook-url:
        type: string
        default: ''
        description: The URL of the Slack webhook.
      webhook-url-env-var:
        type: string
        default: SLACK_WEBHOOK
        description: |
          The name of the environment variable configured in CircleCI that contains the Slack webhook URL
    steps:
      - run:
          name: Send a message to Slack via a webhook
          command: |
            # Put the json payload into a slack.json file to avoid interpeting it
            cat > slack.json \<<'SLACK-PAYLOAD-4FC4D2195631E5-EOF'
            << parameters.json-payload >>
            SLACK-PAYLOAD-4FC4D2195631E5-EOF

            # The directly-specified URL overrides the environment variable, if supplied
            if [[ "<< parameters.webhook-url >>" ]]; then
              << parameters.webhook-url-env-var >>=<< parameters.webhook-url >>
            fi

            if [[ -z "$<< parameters.webhook-url-env-var >>" ]]; then
              1>&2 echo "Webhook URL is not defined.
              Please supply webhook-url or webhook-url-env-var arguments to slack-webhook orb,
              or set the SLACK_WEBHOOK environment vairable."
              exit 1
            fi

            # Call the webhook
            curl -H 'Content-type: application/json' --data-binary @slack.json $<< parameters.webhook-url-env-var >>

examples:
  webhook-url:
    description: |
      Provide the webhook URL directly in the webhook-url parameter.

      Note that this leaks the Webhook URL in your CircleCI config and the CircleCI logs - using one of the environment variable options below is recommended.

      To generate a webhook URL, please see the Slack instructions: https://api.slack.com/messaging/webhooks
      The json payload can be generated with the Slack Block Kit Builder: https://app.slack.com/block-kit-builder

      Unfortunately the json payload example below is reformatted by the CircleCI documentation generator. Please check the original in the Orb Source at the bottom of the page for an easier to read example.

    usage:
      version: 2.1

      orbs:
        slack-webhook: adamu/slack-webhook@1.0.0

      jobs:
        build:
          docker:
            - image: cimg/base:stable
          steps:
            - slack-webhook/send-message:
                webhook-url: https://hooks.slack.com/...
                json-payload: |
                  {
                    "blocks": [
                      {
                        "type": "section",
                        "text": {
                          "type": "mrkdwn",
                          "text": "Hello from <https://github.com/adamu|@adamu>'s `slack-webhook` CircleCi orb! 👋"
                        }
                      }
                    ]
                  }
  environment-variable:
    description: |
      Set the webhook URL in the SLACK_WEBHOOK environment variable on CircleCI.
      When using this method, only the json-payload parameter needs to be supplied.

      To generate a webhook URL, please see the Slack instructions: https://api.slack.com/messaging/webhooks
      The payload can be generated with the Slack Block Kit Builder: https://app.slack.com/block-kit-builder

      Unfortunately the json payload example below is reformatted by the CircleCI documentation generator. Please check the original in the Orb Source at the bottom of the page for an easier to read example.
    usage:
      version: 2.1

      orbs:
        slack-webhook: adamu/slack-webhook@1.0.0

      jobs:
        build:
          docker:
            - image: cimg/base:stable
          steps:
            - slack-webhook/send-message:
                json-payload: |
                  {
                    "blocks": [
                      {
                        "type": "section",
                        "text": {
                          "type": "mrkdwn",
                          "text": "Hello from <https://github.com/adamu|@adamu>'s `slack-webhook` CircleCi orb! 👋"
                        }
                      }
                    ]
                  }
  custom-environment-variable:
    description: |
      Set the webhook URL in a custom environment variable configured on CircleCI, and provide the name of the environment variable in the webhook-url-env-var parameter.

      To generate a webhook URL, please see the Slack instructions: https://api.slack.com/messaging/webhooks
      The payload can be generated with the Slack Block Kit Builder: https://app.slack.com/block-kit-builder

      Unfortunately the json payload example below is reformatted by the CircleCI documentation generator. Please check the original in the Orb Source at the bottom of the page for an easier to read example.
    usage:
      version: 2.1

      orbs:
        slack-webhook: adamu/slack-webhook@1.0.0

      jobs:
        build:
          docker:
            - image: cimg/base:stable
          steps:
            - slack-webhook/send-message:
                webhook-url-env-var: CUSTOM_SLACK_WEBHOOK_VARIABLE
                json-payload: |
                  {
                    "blocks": [
                      {
                        "type": "section",
                        "text": {
                          "type": "mrkdwn",
                          "text": "Hello from <https://github.com/adamu|@adamu>'s `slack-webhook` CircleCi orb! 👋"
                        }
                      }
                    ]
                  }