Add webhooks documentation (#25)

* Add webhooks and format other pages

* Spelling fixes

* Add integration overview

Author: jonerickson

docs/.vitepress/config.js

@@ -48,7 +48,6 @@ export default {
           { text: 'Getting Started', link: '/getting-started' },
           { text: 'Pricing', link: '/pricing' },
           { text: 'Registration', link: '/registration' },
-          { text: 'Status', link: '/status' },
           { text: 'Support', link: '/support' }
         ]
       },
@@ -88,6 +87,10 @@ export default {
         text: 'External Integration',
         collapse: false,
         items: [
+          {
+            text: 'Overview',
+            link: '/external-integration/overview'
+          },
           {
             text: 'API',
             collapsed: true,
@@ -100,6 +103,10 @@ export default {
             link: '/external-integration/oauth',
             items: [{ text: 'OpenID Connect', link: '/external-integration/oauth/oidc' }]
           },
+          {
+            text: 'Webhooks',
+            link: '/external-integration/webhooks'
+          },
           {
             text: 'Widgets',
             collapsed: true,

docs/about.md

@@ -1,19 +1,20 @@
 # About
 
-PERSCOM.io is the ultimate solution for organizations utilizing a para-military structure looking to manage their personnel. Our platform
+PERSCOM.io is the ultimate solution for organizations looking to manage their personnel more efficiently and effectively. Our platform
 offers a comprehensive suite of tools to help you keep track of all aspects of personnel management, from records and qualification
-tracking, calendar and event management to personnel organization and custom data management.
+tracking, calendar and event management, and external application integration to personnel organization and custom data management.
 
 With PERSCOM.io, you can easily manage personnel information, track their qualifications, and monitor their performance. Our software also
-allows you to create custom positions and specialties, as well as define your organization structure with units.
+allows you to create custom positions and specialties and define your organization structure with units.
 
 We understand the importance of integrating your data with other systems, which is why we offer the ability to integrate with any
-third-party service through our API, OAuth 2.0 or the library of Widgets. Additionally, our platform offers the ability to create custom
-forms and track submissions, making it easy for you to collect data and manage your personnel information.
+third-party service through our [API](/external-integration/api), [OAuth 2.0](/external-integration/oauth),
+[Webhooks](/external-integration/webhooks), or the library of [Widgets](/external-integration/widgets). Additionally, our platform offers
+the ability to create custom forms and track submissions, making it easy for you to collect data and manage your personnel information.
 
-PERSCOM.io is designed to be user-friendly and accessible from anywhere, so you can manage your personnel from the office, the field, or
-on-the-go. With our comprehensive platform, you can simplify your personnel management processes and focus on what's truly important - your
+PERSCOM.io is designed to be user-friendly and accessible from anywhere, so you can manage your personnel from the office, the field, or on
+the go. With our comprehensive platform, you can simplify your personnel management processes and focus on what's truly important - your
 mission.
 
-Join the revolution in para-military personnel management and see the difference PERSCOM.io can make for your organization. Sign up for a
+Join the revolution in personnel management and see the difference PERSCOM.io can make for your organization. Sign up for a
 [demo](https://perscom.io/register) today and take the first step towards a more efficient and effective way of managing your personnel.

docs/external-integration/api.md

@@ -1,7 +1,18 @@
 # API
 
 The PERSCOM.io API is the backbone that allows PERSCOM.io to function and deliver the services you've come to enjoy. The API also allow you
-to integrate your PERSCOM.io data with third-party services.
+to integrate your PERSCOM.io data with third-party services and applications.
+
+An API, or Application Programming Interface, is a set of protocols, tools, and standards for building software applications. APIs define
+how different software components should interact with each other and enable developers to integrate their own software with existing
+applications and services.
+
+In other words, an API provides a standardized way for different software systems to communicate and exchange data. This allows developers
+to build new applications that can "talk" to existing software without needing to understand the details of how that software is
+implemented.
+
+The PERSCOM.io API is built using the `REST` interface. A request to the PERSCOM.io API requires a `GET`, `POST`, `PUT`, or `DELETE` HTTP
+request along with an API key and your PERSCOM ID to an available URL endpoint. Details on how to perform those requests are outlined below.
 
 ## API Keys
 

docs/external-integration/oauth.md

@@ -1,11 +1,12 @@
 # OAuth 2.0
 
-OAuth 2.0 is an authorization protocol that enables third-party applications to access your organization's data without giving them your
-username and password. When you grant permission to an application using OAuth 2.0, you are essentially allowing it to access specific parts
-of your data on your behalf. This can be beneficial in several ways. For example, if you use an external timekeeping or scheduling software,
-you can use our OAuth 2.0 feature to allow that software to access your organization's personnel data. This can save you time and effort by
-automating the data transfer process and reducing manual data entry errors. With OAuth 2.0, you can have more control over which third-party
-applications can access your organization's data, and you can revoke their access at any time if needed.
+OAuth 2.0 is an authorization protocol, built on top of the PERSCOM.io API, that enables third-party applications to access your
+organization's data without giving them your username and password. When you grant permission to an application using OAuth 2.0, you are
+essentially allowing it to access specific parts of your data on your behalf. This can be beneficial in several ways. For example, if you
+use an external timekeeping or scheduling software, you can use our OAuth 2.0 feature to allow that software to access your organization's
+personnel data. This can save you time and effort by automating the data transfer process and reducing manual data entry errors. With OAuth
+2.0, you can have more control over which third-party applications can access your organization's data, and you can revoke their access at
+any time if needed.
 
 ## Grants
 
@@ -17,7 +18,7 @@ authorize access to protected resources. The four main types of authorization gr
   application exchanging an authorization code for an access token.
 - Implicit grant: This grant type is similar to the authorization code grant, but is used for browser-based applications where the client
   secret cannot be kept secret. The access token is returned directly to the client instead of being exchanged for an authorization code.
-- Resource owner password credentials grant: This grant type is used when the client already has the user's username and password, and needs
+- Resource owner password credentials grant: This grant type is used when the client already has the user's username and password and needs
   to obtain an access token directly from the authorization server.
 - Client credentials grant: This grant type is used when the client needs to access its own resources, rather than a user's resources. It
   involves the client providing its own credentials to the authorization server to obtain an access token.
@@ -26,7 +27,7 @@ authorize access to protected resources. The four main types of authorization gr
 
 In the context of OAuth 2.0, scopes are used to specify the level of access that a client application has to a protected resource. When a
 client application requests authorization to access a protected resource, it specifies one or more scopes that it requires. The
-authorization server then grants an access token that has permissions to access only the specified scopes. Scopes provide a way to limit the
+authorization server then grants an access token that has permission to access only the specified scopes. Scopes provide a way to limit the
 access granted to a client application, reducing the risk of unauthorized access to sensitive data. For example, an application that needs
 to read a user's email address may request access to the "view:user" scope, but not to other sensitive scopes such as "update:user" or
 "delete:user".

docs/external-integration/oauth/oidc.md

@@ -2,16 +2,16 @@
 
 OIDC stands for OpenID Connect, which is a widely-used authentication protocol built on top of OAuth 2.0. While OAuth 2.0 is primarily
 designed for granting access to APIs, OIDC focuses on user authentication. OIDC allows a user to authenticate with a provider (e.g., Google,
-Facebook, or your own identity provider), and then receive an ID token that contains information about the user. This information can be
-used to log the user into a web application, among other things.
+Facebook, or your identity provider) and then receive an ID token containing information about the user. This information can be used to log
+the user into a web application, among other things.
 
-OIDC defines a set of standard [endpoints](#endpoints) that the client application can use to interact with the identity provider to
-authenticate a user and receive the ID token. These endpoints include a discovery endpoint, an authorization endpoint, and a token endpoint.
-The discovery endpoint allows the client to discover the endpoints and configuration of the provider, while the authorization endpoint is
-used to initiate the authentication process. Finally, the token endpoint is used to exchange an authorization code for an ID token.
+OIDC defines a set of standard [endpoints](#endpoints) that the client application can use to authenticate a user and receive the ID token
+to interact with the identity provider. These endpoints include a discovery endpoint, an authorization endpoint, and a token endpoint. The
+discovery endpoint allows the client to discover the endpoints and configuration of the provider, while the authorization endpoint is used
+to initiate the authentication process. Finally, the token endpoint is used to exchange an authorization code for an ID token.
 
 In summary, OIDC provides a standardized way to authenticate users and obtain information about them, making it easier to build secure and
-scalable web applications as well as implmenent Single Sign-On (SSO) with third-party applications.
+scalable web applications as well as implement Single Sign-On (SSO) with third-party applications.
 
 ## Endpoints
 
@@ -60,7 +60,7 @@ curl -X GET \
 Returns information about the currently signed-in user.
 
 The `access token` must have the `openid` scope. The endpoint also excepts the `profile` and `email` scope that will return the respective
-fields in the response, but is not required. The best practice would be to include all three scopes when requesting an access token.
+fields in the response but is not required. The best practice would be to include all three scopes when requesting an access token.
 
 ```vb
 curl -X GET \

docs/external-integration/overview.md

@@ -0,0 +1,78 @@
+# External Integration Overview
+
+PERSCOM.io provides a vast array of different options to integrate your personnel data with third-party services. These services include the
+PERSCOM.io [API](/external-integration/api), [OAuth 2.0](/external-integration/oauth),
+[OpenID Connect (OIDC)](/external-integration/oauth/oidc), [Webhooks](/external-integration/webhooks), and
+[Widgets](/external-integration/widgets). Visit the individual integrations page to view more information and how-to's on how to integrate
+these services.
+
+## Choosing an Integration
+
+Below is a brief overview of each integration and the best use cases for each.
+
+### API
+
+The PERSCOM.io API is a RESTful HTTP interface for interacting with your personnel data on a machine to machine level. The API would be best
+used for:
+
+- Querying personnel data for reports and analysis
+- Automating business workflows
+- Building custom software that will consume and display PERSCOM.io personnel data
+- Updating and managing personnel data from a third-party software
+
+### OAuth 2.0
+
+OAuth 2.0 is an authorization protocol, built on top of the PERSCOM.io API, that enables third-party applications to access your
+organization's data without giving them your username and password. Here are some common use cases where OAuth 2.0 might be used:
+
+1. Single Sign-On (SSO): OAuth 2.0 can be used to enable SSO across multiple applications. A user can authenticate once, and then use that
+   authentication to access other applications without having to log in again.
+2. Accessing PERSCOM.io API: OAuth 2.0 can be used to allow an application to access data from PERSCOM.io via the API. This is useful when
+   an application needs to access data that is not stored locally.
+3. Mobile and Web Applications: OAuth 2.0 can be used to secure mobile and web applications, allowing users to log in using their
+   credentials from another service. This is particularly useful for mobile applications, where users may not want to enter their
+   credentials into a small screen.
+4. Enterprise Applications: OAuth 2.0 can be used to secure enterprise applications, allowing users to access resources across multiple
+   applications without having to authenticate multiple times.
+
+### OpenID Connect (OIDC)
+
+OIDC is an authentication protocol that is built on top of OAuth 2.0. OIDC outlines a standard protocol for providing useable data about an
+authenticated user that can be used for third-party services to consume. Here are some common uses cases for OIDC:
+
+1. Single Sign-On (SSO): OIDC can be used to enable SSO across multiple applications. A user can authenticate once, and then use that
+   authentication to access other applications without having to log in again. OIDC provides a standardized way for applications to verify a
+   user's identity and access tokens, which can be used to access other resources.
+2. Identity Verification: OIDC can be used to verify a user's identity. When a user logs in, the OIDC provider sends an ID token to the
+   application that contains information about the user, such as their name and email address. The application can use this information to
+   verify the user's identity.
+3. Authorization: OIDC can be used to authorize access to resources. Applications can use OIDC to obtain access tokens that can be used to
+   access protected resources.
+4. Mobile and Web Applications: OIDC can be used to secure mobile and web applications, allowing users to log in using their credentials
+   from another service. This is particularly useful for mobile applications, where users may not want to enter their credentials into a
+   small screen.
+
+### Webhooks
+
+Webhooks can be used to enable real-time notifications and data updates for third-party services, such as a messaging platform, an external
+database or a custom reporting tool. Here are some common use cases for webhooks:
+
+1. Automated Workflows: Webhooks can be used to trigger automated workflows between applications. For example, when a new user is added to
+   PERSCOM.io, a webhook can automatically trigger the creation of a new record in a project management tool.
+2. Notifications: Webhooks can be used to send notifications to users or applications. For example, when a user completes a form, a webhook
+   can be used to send a notification to start importing the user data into other managed services.
+3. Data Synchronization: Webhooks can be used to keep data synchronized between applications. For example, when a user updates their contact
+   information in PERSCOM.io, a webhook can be used to update the information in other connected applications.
+4. Real-Time Data Transfer: Webhooks allow for real-time data transfer between applications. This is useful for applications that require
+   real-time data, such as chat applications or real-time analytics.
+
+### Widgets
+
+Widgets provide a way to display your personnel data within another third-party service via HTML and Javascript. PERSCOM.io offers the
+following embeddable widgets:
+
+1. Roster and Personnel Files
+2. Awards
+3. Ranks
+4. Qualifications
+5. Calendar and Events