# Events, Notifications, Webhooks

CloudTruth allows you to subscribe to events. 

Use the example code below to configure sending a notification to a Slack channel. 

POST to `/api/v1/webhooks/` with a payload

```
{
  "name": "MyNewWebhook",
  "event_types": [
    "parameter_created"
  ],
  "type": "slack",
  "configuration": {
    "token": "string",
    "channel": "string",
    "username": "string"
  },
  "organization": "string"
}
```

`organization` is the organization ID for the installing org. I don't know how to advise a user to get this info and we might want to remove it from the request and just infer it in the same way we usually do.

`event_types` can be a list containing any combination of these items:

```
    "parameter_created"
    "parameter_updated"
    "parameter_deleted"
    "project_created"
    "project_updated"
    "project_deleted"
    "environment_created"
    "environment_updated"
    "environment_deleted"
    "value_created"
    "value_updated"
    "value_deleted"
```

`type` can only be slack, until we implement a different event handler

`configuration` is a JSON field that requires three keys (these are service-specific, this example is only for Slack):

```
{
    "token": <should be generated from Slack admin>,
    "channel": <should be the channel name to deliver messages to>,
    "username": <text to use for the username for the message into Slack>,
}
```

To generate a Slack API token:

1. Go to <https://api.slack.com/apps>
2. Click "Create New App"
3. Select "From a manifest"
4. Paste in the provided manifest (below)
5. Click "Create"
6. Click "OAuth & Permissions" on the left nav
7. Click the "Install to " button
8. Copy the generated Bot User OAuth Token

Slack App Manifest:

```
{
    "display_information": {
        "name": "CloudTruth Webhook"
    },
    "features": {
        "bot_user": {
            "display_name": "CloudTruth Webhook",
            "always_online": false
        }
    },
    "oauth_config": {
        "scopes": {
            "bot": [
                "chat:write.public",
                "chat:write"
            ]
        }
    },
    "settings": {
        "org_deploy_enabled": false,
        "socket_mode_enabled": false,
        "token_rotation_enabled": false
    }
}
```