diff --git a/docs/receiving/receiving-with-ingest.mdx b/docs/receiving/receiving-with-ingest.mdx new file mode 100644 index 0000000..97b310a --- /dev/null +++ b/docs/receiving/receiving-with-ingest.mdx @@ -0,0 +1,107 @@ +--- +title: Receiving Webhooks with Ingest +--- + +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 `unverified` to skip +performing signature verification. This is useful for providers that have no +verification scheme and for providers whose verification scheme is not 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`. + +```shell +curl https://api.svix.com/ingest/api/v1/source \ + -H "Authorization: Bearer $SVIX_TOKEN" \ + -H "Content-Type: application/json" \ + -d @- << EOF +{ + "name": "from-github", + "uid": "from-github", + "type": "github", + "config": { + "secret": "" + } +} +EOF +``` + + +## 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` and is also used to generate the `Uid` +for the Svix `Application`. The `Uid` will be: `app_`. + +Managing this companion `Application` for the `Source` is how you can +configure endpoints to forward the incoming webhooks to, 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: + +```shell +curl https://api.svix.com/ingest/api/v1/source/src_xxxxx/token/rotate \ + -H "Authorization: Bearer $SVIX_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{}' +``` + +`Token`s that are rotated stay usable for 24 hours. 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",