Integrate Actions with Slack

[jamesefhawkins]

Is your feature request related to a problem? Please describe.

• There are a couple of key actions that users may take that I really want to know in real time.
  • ie: if a user signs up to use the service, I would like to send them a personal email saying something nice, tailored to them. Doing this in real time is important because I'd like to make sure if they have any issues during the install, I can help them as they're working, that we feel accessible.
• Events are important to many people in our company. Connecting it with Slack would help make sure every person takes a data-driven approach to data, AND it'd likely raise more use cases for other teams.
• The app is hard to use on cell phones, whereas Slack and email work well.

Describe the solution you'd like

• I would like to receive an email or a Slack notification when an Action takes place.
• The notification should contain a link to the Event, showing the (i) event properties (ii) person (iii) path (iv) when it took place.

Describe alternatives you've considered

• Put my phone down, go to my computer, open the app and hunt for the information. If I am out and about, I cannot do this.

Additional context
Add any other context or screenshots about the feature request here.

[timgl]

In reality, I think this is a ticket to "call any integration if a certain action is triggered". This is going to require a couple of things:

• Workers(!)
• I think we should detach this from a 1-1 event happens -> call action, as I think at some point we'll want to do things like "Send me a notification if this action happens 1000x times" or "send me a notification if this action happens more/less often than usual". At the moment it's fine to just do a simple action happens -> notification.
• have some kind of base class that integrations can inherit from. Those base classes should define the common hooks for this.

[mariusandra]

Hi everyone!

After having a look at this task, there are a few things we can do here. I'll list the options here along with my suggestions.

1. How to integrate with Slack.

At the end of the day, PostHog should get an "incoming webhook url" from Slack (something like https://hooks.slack.com/services/TTTTT/BBBBBB/gibberishcode) and just POST the messages there. To get this URL there are two options:

Option 1: Every man for himself (same for every woman) - incoming webhooks

For each instance of posthog that you manage, you go to https://api.slack.com/apps?new_app=1 and create a new app.

You will probably call the app "PostHog" or "HogBot" or "PostBot" or "Sonic the HedgeHapp" and then upload a cute logo to go with it.

Then you open the page "incoming webhooks" and click the "add a new webhook" button. In the dialog that opens you select the channel the webhook will be post to:

You then get a webhook URL that you copy to the /setup page on PostHog. This will then be stored on the Team model.

Option 2: OAuth and magic - slack buttons

The second option has more steps, but looks best for the end user... if the end user is using the hosted app. It gets tricky if we factor in self-hosting.

What we need in this case is to 1) make a new slack app like above, 2) give posthog the client ID and the client secret. These client ID and secret should then be stored per app, not per team.

Then you go to /setup and click on a "Add to Slack" button.

This will open a modal similar to the one from the step above that will ask you to choose the channel. Selecting it will send a response pack to the app, which will get a token.. and using that will get the webhook url. This webhook url should then again be stored on the Team.

...

For now I implemented option 1 (PR #460), as at the end of the day we will anyway need to store the webhook url on the team. However for the hosted app.posthog.com instance, this will require the end user to jump through more hoops than they should and we should think of what to do with option 2.

For now I implemented a very naïve approach that just posts everything without any rate limiting or background workers.

The steps implemented:

1. Under /setup you specify the webhook URL:

2. For each action you tick the checkbox when editing it to post to slack:

3. You get a very basic action in Slack:

...

Any questions regarding the implementation so far? I have some myself:

• What to do regarding options 1 and 2 above? If going for option 2, where should we store the client ID and secret for the app? In ENV variables? Somewhere else that can be configured by the user/admin?
• Should we support just one webhook (and thus one channel for notifications) per team... or multiple? So that you can choose the webhook when editing the action
• Thoughts on how to do rate limiting and what options should we have for the posting of the actions? E.g. how to display the "post every action" vs "post every 100th action" option? Or this is for the future?
• What URL should the posted action link to?

Things still to do:

• do this posting in a background worker
• remove the webhook if it fails with an error that says "this webhook was removed"
• figure out some form of rate limiting system so we don't overload slack

[jamesefhawkins]

Thanks for getting the quick version live!

Re option 2, I'd have thought we could create a 'global' slack service, that users' self-hosted versions could post to, to run as its own service.

That way we could make it feel like a one click button. The downsides I'd see would be:

• Some more work for us
• It's not quite as user privacy friendly. We'd just need to explain what's happening with their data if there isn't already a permissions message from Slack.

The advantages:

• Simple user experience (if this is possible?)
• This approach is probably what we'd need to do for any other integration with a major service (Salesforce/mailchimp/whatever else) to prevent users having to do so much work to integrate a self hosted app.

[timgl]

Let's just get this out as is and see if people use this. I'll comment a few small tweaks in the PR.

[mariusandra]

Hi all, this is starting to take shape. @timgl and @jamesefhawkins , if you have and feedback please let me know!

What's implemented now.

1. Under "setup" you have a new box where you can publish a Slack webhook URL

At the end of the day, every integration will require a webhook of some sort, so it's the obvious starting point. We can make finding and fetching this webhook more automatic in the future.

2. If you save a new URL, we will also automatically send you a test to make sure the integration works:

3. The errors are currently presented to the user in a developer-friendly way, meaning we show directly the message slack gives us.

4. When you add/edit an action, you have a checkbox that lets you opt in to receiving messages about this error in slack:

(The checkbox is also there when you don't have slack integrated, just grayed out)

5. Actions are sent to slack in the background (in the worker) after an event has been created. Right now the text on the action is very very basic. If the event creates more than one action, they are grouped into the same line:

Currently it only shows the distinct ID of the user... not even the name or anything. This is still to come!

Questions

1. How to show the actions and where should the link take us? As discussed in the standup it will currently just open the /person/ID page, yet this for me at least has no mention of actions. So if you're looking for a "demo first page" action, you'll have to remember that this happened when the URL is "/demo/1".

2. When a webhook is deactivated from Slack, we will continue sending events its way unless the user disables it in /setup.

I was thinking of automatically doing it if Slack returns with "invalid_token", "team_disabled" or any of the other permanent errors. However should be somehow inform the user/admin about this? Either via SMTP or should we have somewhere a "system log" where the user/admin gets messages, alerts, etc?

3. This is the very basic MVP integration that requires a lot of setup: you need to create your own slack app. As you can see from the screenshots, I was too lazy to even add a logo to mine.

We can't expect all users to want to do this. If you're self-hosting, you might want to do it for privacy reasons, but I'm sure even some self-hosted people would prefer a nicer interface.

What we can do are:
a) option 2 from the comment above - where for instances like app.posthog.com, we would set up a slack app beforehand and provide a "add to slack" button that configures this app:
b) Try to do what James suggested in his comment. I still need to think about it and see what are the possibilities. It's possible all messages will need to go through a "slack proxy service" (that we'll need to host on heroku separately)... or maybe it can just help register the self-hosted posthog instances and retuns webhooks that they will use to talk to slack directly. I don't know right now...

[timgl]

This is very cool! To answer your questions:

1. You're right, that's a good point. I think the least confusing solution for now is to just link to actions instead (/action/[id])?
2. I don't think we need to worry about this for now.
3. Agree it'd be cool to do this -- let's create another ticket so we can get this MVP out.

[jamesefhawkins]

This is great. I suspect eventually we will replace that 'Post to Slack when this action is triggered.' message with a range of options (Elementor does a good basic job of handling this in their form submissions):

1. /action/id - agreed. I think most users will want to know "who" rather than "what" - the action here gives you both and is the most intuitive.
2. We probably need a messages thing at some stage. This could also have alerts for 'worker configuration error' as discussed, maybe as a notification icon at the top that pops open with a sidebar, as is fairly standard on lots of other software. In the short run, I don't think this is a problem until someone is using it. In the short run, let's see if anyone uses it before making it more solid.
3. This is also fine for now. I'd wait for feedback and a friendly user.

I bet that the first feedback will be "we want to do this on a batch of events happening ie "over X of Action Y in a day". That said, individual actions (sign ups) would be useful too.

[mariusandra]

Hi!

1. Instead of linking to actions instead I linked to actions also:
   

2. Ok to defer this for later

3. Same as 2

[mariusandra]

Great! PR #460 should be done then. I also added the documentation here: PostHog/docs#6

[timgl]

Done!