Skip to content

Commit a256ccc

Browse files
committed
Add docs for ingest
1 parent 723ad52 commit a256ccc

File tree

2 files changed

+122
-0
lines changed

2 files changed

+122
-0
lines changed
Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
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

sidebars.js

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,9 @@ module.exports = {
3939
"receiving/using-app-portal/replaying-messages",
4040
],
4141
},
42+
{
43+
"Using Ingest": ["receiving/receiving-with-ingest"]
44+
},
4245
{
4346
"Verifying Webhooks": [
4447
"receiving/verifying-payloads/why",

0 commit comments

Comments
 (0)