Skip to main content

Using the Ingest API

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.

curl https://api.svix.com/ingest/api/v1/source \
  -H "Authorization: Bearer $SVIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d @- << EOF
{
  "name": "from-github",
  "description": "receives webhooks from GitHub",
  "uid": "from-github",
  "type": "github",
  "config": {
    "secret": "<the signing 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_<the source id>.

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:

curl https://api.svix.com/ingest/api/v1/source/src_xxxxx/token/rotate \
  -H "Authorization: Bearer $SVIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Tokens that are rotated stay viable for 24 hours. During this time both the old and new Tokens 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.