Add Webhook Integration Guide

[it33]

trafficstars

We should add high level instructions on how to set up webhook integrations, and estimate the time and effort involved, and skill set required. This is important for both customers and implementation partners planning deployments.

Integrations with Custom Systems

Integrations to over 700 SaaS apps can be set up quickly using Zapier. The following guide walks through the set up of private cloud integrations on your infrastructure with your custom systems.

Skills Required:

• Web development experience (ability to send and receive HTTP request/responses, being able to process and convert inputs)
• Basic web security, to secure the integration
• Knowledge of 3rd party application to which you're integration
• Knowledge of Mattermost integration infrastructure (can be learned from documentation[link])

Time and effort

• For a mid-level web developer who understands the 3rd party application, estimate 0.5 to 1.0 days of development work for the first integration and 0.2 to 0.5 days for subsequent integrations.

Process:

1. Review existing library of open source integrations to find examples written in a programming language with which you are familiar (Python, JavaScript, Java, PHP, etc.) to use as a starting point--ideally one similar to your desired functionality, but perhaps integrating with a different product.

2. Either starting with an open source integration, or writing something completely new, create a service to serve the logic of your integration using a programming language with which you are most comfortable.

3. For developing an incoming integration, pushing information into Mattermost based on events in a 3rd party application:

   a. Set up service to call Mattermost incoming webhook [link]

   b. Set up your 3rd party application to call your service when an event is triggered, passing in any appropriate parameters. Example: See sample GitLab integration with Mattermost: https://github.com/NotSqrt/mattermost-integration-gitlab

   c. Translate the parameters passed in by the 3rd party application into a format that renders with the Mattermost webhook as you wish.

4. For developing an outgoing integration, triggering an action in a 3rd party application based on posting a keyword in a Mattermost channel:

   a. Set up service to be called by an outgoing Mattermost webhook [link] when a keyword is posted in a message.

   b. Set up your 3rd party application to be called from your service when triggered by the Mattermost outgoing webhook, passing in parameters as appropriate. Example: See sample Giphy integration with Mattermost: https://github.com/numberly/mattermost-integration-giphy

5. Secure your endpoints. Typically endpoints are hosted in a private network. Each uses an obscure token. You can also set up point-to-point security per your organizations standard policies.

[justinegeffen]

This is a great suggestion and one that could form part of the onboarding/growth spike. Passing to @aaronrothschild for feedback and @BenLloydPearson for input.

[BenLloydPearson]

This seems to align with our goals to produce more practical educational guides for building integrations. I'm more than happy to take this on, but I'll need to prioritize it against other content we're planning.