restore option to send slack messages via webhooks

Treat webhooks as a fallback option in case access token isn't defined

Author: yasunariw

documentation/secret_docs.md

@@ -17,7 +17,10 @@ A secrets file stores sensitive information. Unlike the repository configuration
 |-|-|-|-|
 | `gh_token` | specify to grant the bot access to private repositories; omit for public repositories | Yes | - |
 | `gh_hook_token` | specify to ensure the bot only receives GitHub notifications from pre-approved repositories | Yes | - |
-| `slack_access_token` | slack bot token obtained via [oauth](https://api.slack.com/authentication/oauth-v2), enabling message posting to the workspace | Yes | - |
+| `slack_access_token` | slack bot access token to enable message posting to the workspace | Yes | try to use webhooks defined in `slack_hooks` instead |
+| `slack_hooks` | list of channel names and their corresponding webhook endpoint | Yes | try to use token defined in `slack_access_token` instead |
+
+Note that either `slack_access_token` or `slack_hooks` must be defined.
 
 ## `gh_token`
 
@@ -26,3 +29,22 @@ Some operations, such as fetching a config file from a private repository, or th
 ## `gh_hook_token`
 
 Refer [here](https://docs.github.com/en/free-pro-team@latest/developers/webhooks-and-events/securing-your-webhooks) for more information on securing webhooks with a token.
+
+## `slack_access_token`
+
+Refer [here](https://api.slack.com/authentication/oauth-v2) for obtaining an access token via OAuth.
+
+## `slack_hooks`
+
+*Note: If `slack_access_token` is also defined, the bot will authenticate over Slack's Web API and this option will not be used.*
+
+Expected format:
+
+```json
+{
+    "channel": "channel name",
+    "url": "webhook url"
+}
+```
+
+Refer [here](https://api.slack.com/messaging/webhooks) for obtaining a webhook for a channel.

lib/api_remote.ml

@@ -50,24 +50,34 @@ end
 module Slack : Api.Slack = struct
   let log = Log.from "slack"
 
-  let send_notification ~(ctx : Context.t) ~msg =
+  let bearer_token_header access_token = sprintf "Authorization: Bearer %s" access_token
+
+  (** `send_notification ctx msg` notifies `msg.channel` with the payload `msg`;
+      uses web API with access token if available, or with webhook otherwise *)
+  let send_notification ~(ctx : Context.t) ~(msg : Slack_t.post_message_req) =
+    let build_error e = fmt_error "%s\nfailed to send Slack notification" e in
+    let build_query_error url e = build_error @@ sprintf "error while querying %s: %s" url e in
     let secrets = Context.get_secrets_exn ctx in
-    match secrets.slack_access_token with
-    | None -> Lwt.return @@ fmt_error "failed to retrieve Slack access token"
-    | Some access_token ->
-      let url = "https://slack.com/api/chat.postMessage" in
+    let headers, url, webhook_mode =
+      match secrets.slack_access_token with
+      | Some access_token -> [ bearer_token_header access_token ], Some "https://slack.com/api/chat.postMessage", false
+      | None -> [], Context.hook_of_channel ctx msg.channel, true
+    in
+    match url with
+    | None -> Lwt.return @@ build_error @@ sprintf "no token or webhook configured to notify channel %s" msg.channel
+    | Some url ->
       let data = Slack_j.string_of_post_message_req msg in
-      let headers = [ sprintf "Authorization: Bearer %s" access_token ] in
       let body = `Raw ("application/json", data) in
       log#info "sending to %s : %s" msg.channel data;
       ( match%lwt http_request ~body ~headers `POST url with
+      (* error detection in response: slack uses status codes for webhooks versus a 200 code w/ `error` field for web api *)
       | Ok s ->
-        let res = Slack_j.post_message_res_of_string s in
-        if res.ok then Lwt.return @@ Ok ()
+        if webhook_mode then Lwt.return @@ Ok ()
         else (
-          let msg = Option.value ~default:"an unknown error occurred" res.error in
-          Lwt.return @@ fmt_error "%s\nfailed to send Slack notification" msg
+          let res = Slack_j.post_message_res_of_string s in
+          if res.ok then Lwt.return @@ Ok ()
+          else Lwt.return @@ build_query_error url (Option.value ~default:"an unknown error occurred" res.error)
         )
-      | Error e -> Lwt.return @@ fmt_error "error while querying %s: %s\nfailed to send Slack notification" url e
+      | Error e -> Lwt.return @@ build_query_error url e
       )
 end

lib/config.atd

@@ -30,13 +30,21 @@ type config = {
   ?main_branch_name : string nullable; (* the name of the main branch; used to filter out notifications about merges of main branch into other branches *)
 }
 
+(* This specifies the Slack webhook to query to post to the channel with the given name *)
+type webhook = {
+  url : string; (* webhook URL to post the Slack message *)
+  channel : string; (* name of the Slack channel to post the message *)
+}
+
 (* This is the structure of the secrets file which stores sensitive information, and
    shouldn't be checked into version control.  *)
 type secrets = {
   (* GitHub personal access token, if repo access requires it *)
   ?gh_token : string nullable;
   (* GitHub webhook token to secure the webhook *)
   ?gh_hook_token : string nullable;
+  (* list of Slack webhook & channel name pairs *)
+  ~slack_hooks <ocaml default="[]"> : webhook list;
   (* Slack bot token obtained via OAuth, enabling message posting to the workspace *)
   ?slack_access_token : string nullable;
 }

lib/context.ml

@@ -40,6 +40,12 @@ let get_config_exn ctx =
   | None -> context_error "config is uninitialized"
   | Some config -> config
 
+let hook_of_channel ctx channel_name =
+  let secrets = get_secrets_exn ctx in
+  match List.find secrets.slack_hooks ~f:(fun webhook -> String.equal webhook.channel channel_name) with
+  | Some hook -> Some hook.url
+  | None -> None
+
 (** `is_pipeline_allowed ctx p` returns `true` if ctx.config.status_rules
     doesn't define a whitelist of allowed pipelines, or if the list
     contains pipeline `p`; returns `false` otherwise. *)
@@ -61,8 +67,14 @@ let refresh_secrets ctx =
   match get_local_file path with
   | Error e -> fmt_error "error while getting local file: %s\nfailed to get secrets from file %s" e path
   | Ok file ->
-    ctx.secrets <- Some (Config_j.secrets_of_string file);
-    Ok ctx
+    let secrets = Config_j.secrets_of_string file in
+    begin
+      match secrets.slack_access_token, secrets.slack_hooks with
+      | None, [] -> fmt_error "either slack_access_token or slack_hooks must be defined in file '%s'" path
+      | _ ->
+        ctx.secrets <- Some secrets;
+        Ok ctx
+    end
 
 let refresh_state ctx =
   match ctx.state_filepath with

test/secrets.json

@@ -1,4 +1,3 @@
 {
-    "slack_client_id": "",
-    "slack_client_secret": ""
+    "slack_access_token": ""
 }