Add documentation for Stripe webhooks

Author: joshsmith

blueprint/api.apib

@@ -2354,6 +2354,56 @@ This endpoint allows you to check whether a username is valid (by running a vali
 
     + Attributes (Unprocessable Entity Response)
 
+# Group Webhooks - Stripe
+
+Code Corps responds to [Stripe webhooks](https://stripe.com/docs/webhooks).
+
+Since Code Corps is a platform, we have two separate webhook endpoints for dealing with both Stripe Connect (the managed accounts) and the platform (shared data across customers).
+
+## Stripe Connect Webhook [/webhooks/stripe/connect]
+
+Handles Stripe Connect events for managed accounts for projects on the Code Corps platform.
+
+This endpoint provides information about the actual payments and subscriptions that occur on the managed accounts.
+
+### Stripe Connect Webhook [POST]
+
++ Request
+
+    + Attributes
+
+        + object - The Stripe object.
+
+    + Headers
+
+            Content-Type: application/vnd.api+json
+
++ Response 200 (application/vnd.api+json; charset=utf-8)
+
++ Response 400 (application/vnd.api+json; charset=utf-8)
+
+## Stripe Platform Webhook [/webhooks/stripe/platform]
+
+Handles Stripe events for the Code Corps platform itself.
+
+The platform stores Stripe customers and cards so they can be reused across different projects, and fan out updates to all the managed Stripe accounts.
+
+### Stripe Platform Webhook [POST]
+
++ Request
+
+    + Attributes
+
+        + object - The Stripe object.
+
+    + Headers
+
+            Content-Type: application/vnd.api+json
+
++ Response 200 (application/vnd.api+json; charset=utf-8)
+
++ Response 400 (application/vnd.api+json; charset=utf-8)
+
 # Data Structures
 
 ## Category Attributes (object)

lib/code_corps/stripe_service/webhook_processing/connect_event_handler.ex

@@ -1,17 +1,19 @@
 defmodule CodeCorps.StripeService.WebhookProcessing.ConnectEventHandler do
   @moduledoc """
-  In charge of handling Stripe Connect webhooks
+  Handler for Stripe Connect webhooks.
   """
 
   alias CodeCorps.StripeService.Events
 
   @doc """
-  Handles Stripe Connect webhooks
+  Handles Stripe Connect webhook events.
 
   ## Returns
-  * The result of calling the specific handlers `handle/1` function. This result ought ot be a tupple,
-    in which the first member is `:ok`, followed by one or more other elements, usually modified records.
-  * `{:ok, :unhandled_event}` if the specific event is not supported yet or at all
+  * The result of calling the specific handlers `handle/1` function. This
+    result should be a tuple, in which the first member is `:ok`, followed by
+    one or more other elements, usually modified records.
+  * `{:ok, :unhandled_event}` if the specific event is not supported yet
+    or at all
   """
   def handle_event(%{type: type} = attributes), do: do_handle(type, attributes)
 

lib/code_corps/stripe_service/webhook_processing/platform_event_handler.ex

@@ -1,6 +1,6 @@
 defmodule CodeCorps.StripeService.WebhookProcessing.PlatformEventHandler do
   @moduledoc """
-  In charge of handling Stripe Platform webhooks
+  Handler for Stripe Platform webhooks.
   """
 
   alias CodeCorps.StripeService.Events
@@ -9,9 +9,11 @@ defmodule CodeCorps.StripeService.WebhookProcessing.PlatformEventHandler do
   Handles Stripe Platform webhooks
 
   ## Returns
-  * The result of calling the specific handlers `handle/1` function. This result ought ot be a tupple,
-    in which the first member is `:ok`, followed by one or more other elements, usually modified records.
-  * `{:ok, :unhandled_event}` if the specific event is not supported yet or at all
+  * The result of calling the specific handlers `handle/1` function. This
+    result should be a tuple, in which the first member is `:ok`, followed by
+    one or more other elements, usually modified records.
+  * `{:ok, :unhandled_event}` if the specific event is not supported yet
+    or at all
   """
   def handle_event(%{type: type} = attributes), do: do_handle(type, attributes)