|
| 1 | +--- |
| 2 | +title: Ingest Overview |
| 3 | +--- |
| 4 | + |
| 5 | +import CodeTabs from '@theme/CodeTabs'; |
| 6 | +import TabItem from '@theme/TabItem'; |
| 7 | + |
| 8 | +[Svix Ingest] grants you scalability, security best practices, and |
| 9 | +reliability, all with minimal configuration. |
| 10 | + |
| 11 | +Creating a `Source` will generate an endpoint you can share with a webhook |
| 12 | +provider as a destination for their webhooks. |
| 13 | + |
| 14 | +Ingest supports a variety of signature verification schemes used by webhook |
| 15 | +providers. Supported values for a `Source`'s' `type` include: |
| 16 | + |
| 17 | +- `beehiiv` |
| 18 | +- `brex` |
| 19 | +- `clerk` |
| 20 | +- `github` |
| 21 | +- `guesty` |
| 22 | +- `hubspot` |
| 23 | +- `incidentIo` |
| 24 | +- `lithic` |
| 25 | +- `nash` |
| 26 | +- `pleo` |
| 27 | +- `replicate` |
| 28 | +- `resend` |
| 29 | +- `safebase` |
| 30 | +- `sardine` |
| 31 | +- `shopify` |
| 32 | +- `stripe` |
| 33 | +- `stych` |
| 34 | +- `svix` (that's us!) |
| 35 | +- `zoom` |
| 36 | + |
| 37 | +Additionally there's the option to configure a `Source` as `http` that doesn't |
| 38 | +perform any signature verification at all for cases where the provider has no |
| 39 | +signing scheme, or if _they do_ but it isn't yet supported by Ingest. |
| 40 | + |
| 41 | +:::tip |
| 42 | +Let us know if your webhook provider isn't yet supported so we can add it! |
| 43 | +::: |
| 44 | + |
| 45 | + |
| 46 | +## Create a Source |
| 47 | + |
| 48 | +Getting started with Ingest is a matter of configuring a `Source`. |
| 49 | + |
| 50 | +<CodeTabs> |
| 51 | +<TabItem value="curl"> |
| 52 | + |
| 53 | +```sh |
| 54 | +curl https://api.svix.com/ingest/api/v1/source \ |
| 55 | + -X POST \ |
| 56 | + -H "Authorization: Bearer $SVIX_TOKEN" \ |
| 57 | + -H "Content-Type: application/json" \ |
| 58 | + -d @- << EOF |
| 59 | +{ |
| 60 | + "name": "from-github", |
| 61 | + "description": "receives webhooks to from GitHub", |
| 62 | + "uid": "from-github", |
| 63 | + "type": "github", |
| 64 | + "config": { |
| 65 | + "secret": "<the signing secret>" |
| 66 | + } |
| 67 | +} |
| 68 | +EOF |
| 69 | +``` |
| 70 | + |
| 71 | +</TabItem> |
| 72 | +</CodeTabs> |
| 73 | + |
| 74 | +## Tell your provider where to send webhooks |
| 75 | + |
| 76 | +The `SourceOut` response will include an `ingestUrl` which is the endpoint you |
| 77 | +give to your provider, telling them where to send their webhooks. |
| 78 | +For GitHub, as is used in this example, this is referred to as the |
| 79 | +_"Payload URL"_. |
| 80 | + |
| 81 | +## Managing incoming messages |
| 82 | + |
| 83 | +Messages received by Ingest are automatically forwarded to a companion Svix |
| 84 | +`Application`. |
| 85 | + |
| 86 | +The `SourceOut` response also includes an `id` field. |
| 87 | +This `id` appears in the `ingestUrl`, but is also used to generate the `Uid` |
| 88 | +for the Svix `Application`. The `Uid` will be: `app_<the source id>`. |
| 89 | + |
| 90 | +Managing this compainion `Application` for the `Source` is how you can |
| 91 | +configure endpoints, check attempts, retry or recover messages and so on. |
| 92 | +This `Application` also means you can monitor your Ingest Source via the App |
| 93 | +Portal. |
| 94 | + |
| 95 | +## Managing Source Tokens |
| 96 | + |
| 97 | +Finally, the last portion of the `ingestUrl` is a `Token` which can be |
| 98 | +invalidated and rotated: |
| 99 | + |
| 100 | +<CodeTabs> |
| 101 | +<TabItem value="curl"> |
| 102 | + |
| 103 | +```sh |
| 104 | +curl https://api.svix.com/ingest/api/v1/source/src_xxxxx/token/rotate \ |
| 105 | + -X POST \ |
| 106 | + -H "Authorization: Bearer $SVIX_TOKEN" \ |
| 107 | + -H "Content-Type: application/json" \ |
| 108 | + -d '{}' |
| 109 | +``` |
| 110 | + |
| 111 | +</TabItem> |
| 112 | +</CodeTabs> |
| 113 | + |
| 114 | +`Token`s that are rotated stay viable for a short grace period. This during |
| 115 | +this time both the old and new `Token`s are honored by Ingest. During this |
| 116 | +period it's important that you reconfigure your provider with the new |
| 117 | +`ingestUrl` in order to have a seamless transition. |
| 118 | + |
| 119 | +[Svix Ingest]: https://svix.com/ingest |
0 commit comments