From a256cccf22c397ee5d5fe679116eb91666d77169 Mon Sep 17 00:00:00 2001
From: Owen Nelson <onelson@svix.com>
Date: Tue, 3 Dec 2024 23:03:38 -0800
Subject: [PATCH] Add docs for ingest

---
 docs/receiving/receiving-with-ingest.mdx | 119 +++++++++++++++++++++++
 sidebars.js                              |   3 +
 2 files changed, 122 insertions(+)
 create mode 100644 docs/receiving/receiving-with-ingest.mdx

diff --git a/docs/receiving/receiving-with-ingest.mdx b/docs/receiving/receiving-with-ingest.mdx
new file mode 100644
index 0000000..22d320c
--- /dev/null
+++ b/docs/receiving/receiving-with-ingest.mdx
@@ -0,0 +1,119 @@
+---
+title: Ingest Overview
+---
+
+import CodeTabs from '@theme/CodeTabs';
+import TabItem from '@theme/TabItem';
+
+[Svix Ingest] grants you scalability, security best practices, and
+reliability, all with minimal configuration.
+
+Creating a `Source` will generate an endpoint you can share with a webhook
+provider as a destination for their webhooks.
+
+Ingest supports a variety of signature verification schemes used by webhook
+providers. Supported values for a `Source`'s' `type` include:
+
+- `beehiiv`
+- `brex`
+- `clerk`
+- `github`
+- `guesty`
+- `hubspot`
+- `incidentIo`
+- `lithic`
+- `nash`
+- `pleo`
+- `replicate`
+- `resend`
+- `safebase`
+- `sardine`
+- `shopify`
+- `stripe`
+- `stych`
+- `svix` (that's us!)
+- `zoom`
+
+Additionally there's the option to configure a `Source` as `http` that doesn't
+perform any signature verification at all for cases where the provider has no
+signing scheme, or if _they do_ but it isn't yet supported by Ingest.
+
+:::tip
+Let us know if your webhook provider isn't yet supported so we can add it!
+:::
+
+
+## Create a Source
+
+Getting started with Ingest is a matter of configuring a `Source`.
+
+<CodeTabs>
+<TabItem value="curl">
+
+```sh
+curl https://api.svix.com/ingest/api/v1/source \
+  -X POST \
+  -H "Authorization: Bearer $SVIX_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d @- << EOF
+{
+  "name": "from-github",
+  "description": "receives webhooks to from GitHub",
+  "uid": "from-github",
+  "type": "github",
+  "config": {
+    "secret": "<the signing secret>"
+  }
+}
+EOF
+```
+
+</TabItem>
+</CodeTabs>
+
+## Tell your provider where to send webhooks
+
+The `SourceOut` response will include an `ingestUrl` which is the endpoint you
+give to your provider, telling them where to send their webhooks.
+For GitHub, as is used in this example, this is referred to as the
+_"Payload URL"_.
+
+## Managing incoming messages
+
+Messages received by Ingest are automatically forwarded to a companion Svix
+`Application`.
+
+The `SourceOut` response also includes an `id` field.
+This `id` appears in the `ingestUrl`, but is also used to generate the `Uid`
+for the Svix `Application`. The `Uid` will be: `app_<the source id>`.
+
+Managing this compainion `Application` for the `Source` is how you can
+configure endpoints, check attempts, retry or recover messages and so on.
+This `Application` also means you can monitor your Ingest Source via the App
+Portal.
+
+## Managing Source Tokens
+
+Finally, the last portion of the `ingestUrl` is a `Token` which can be
+invalidated and rotated:
+
+<CodeTabs>
+<TabItem value="curl">
+
+```sh
+curl https://api.svix.com/ingest/api/v1/source/src_xxxxx/token/rotate \
+  -X POST \
+  -H "Authorization: Bearer $SVIX_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{}'
+```
+
+</TabItem>
+</CodeTabs>
+
+`Token`s that are rotated stay viable for a short grace period. This during
+this time both the old and new `Token`s are honored by Ingest. During this
+period it's important that you reconfigure your provider with the new
+`ingestUrl` in order to have a seamless transition.
+
+[Svix Ingest]: https://svix.com/ingest
diff --git a/sidebars.js b/sidebars.js
index 5dd217b..60fb9d8 100644
--- a/sidebars.js
+++ b/sidebars.js
@@ -39,6 +39,9 @@ module.exports = {
         "receiving/using-app-portal/replaying-messages",
       ],
     },
+    {
+      "Using Ingest":  ["receiving/receiving-with-ingest"]
+    },
     {
       "Verifying Webhooks": [
         "receiving/verifying-payloads/why",