add documentation for svix-ingest-query and svix-ingest-trailing-path-segments (#310)

part of svix/monorepo-private#12827

depends on svix/svix-webhooks-private#6660

Author: svix-jbrown

content/ingest/receiving-with-ingest.mdx

@@ -199,7 +199,15 @@ The Ingest URL is also listed on the [Ingest Dashboard] for each `Source`.
 
 The `IngestSourceOut` response from the API will include an `ingestUrl` which is
 the endpoint you give to your provider, telling them where to send their
-webhooks.
+webhooks. Given an ingest URL of the format
+`https://api.svix.com/ingest/api/v1/source/src_abcdefghijklmnop/in/token1234567`,
+providers can actually send requests to any trailing path, and with any query parameter; e.g.,
+`https://api.svix.com/ingest/api/v1/source/src_abcdefghijklmnop/in/token1234567/foo/bar/baz?qux=duck`.
+
+Trailing path segments will be forwarded along to the eventual destination under the `svix-ingest-trailing-path-segments` header;
+query parameters will be forwarded under the `svix-ingest-query` header. Both
+are and are also available as [transformations](./transformations.mdx)
+parameters.
 
 For GitHub, as is used in this example, this is referred to as the
 _"Payload URL"_.

content/ingest/transformations.mdx

@@ -26,6 +26,8 @@ Svix expects a Transformation to declare a function named `handler`. Svix will p
 - `method`, a string representing the HTTP method the webhook will be sent with. It is always `"POST"` by default, and its only valid values are `"POST"` or `"PUT"`.
 - `url`, a string representing the destination endpoint's URL. It can be changed to any valid URL.
 - `payload`, which contains the webhook's payload as a JSON object. It can be changed as needed.
+- `eventType`, a string representing the event type. Changes to it are ignored. This will always have the value `svix.in` for ingest events
+- `transformationsParams`, additional parameters made available in ingest; see below for details
 
 The Transformation must return the same object, but may modify its properties as described above.
 In addition to the ones listed above, it can also set the following properties on the returned object:
@@ -47,3 +49,13 @@ function handler(webhook) {
 ```
 
 Great, the webhook is redirected to the custom URL if the `customUrl` property exists on the payload. Otherwise, it is sent to the endpoint's defined URL.
+
+### Ingest-Specific Transformations Params
+
+Transformations called from an Ingest request will receive additional parameters under the `transformationsParams` property. Specifically:
+
+- `transformationsParams.headers` will be a string/string key-value map containing the headers of the input request. If a header is duplicated on the input request, the values will be concatenated with ", ", as per [RFC 9110 § 5.2](https://www.rfc-editor.org/info/rfc9110/#section-5.2).
+- `transformationsParams.headers.svix-ingest-query` contains the un-parsed query string (the part after the `?` on the request URL)
+- `transformationsParams.headers.svix-ingest-trailing-path-segments` contains any parts of the URL after the token, not including the first `/`.
+
+If your source URL is `https://api.svix.com/ingest/api/v1/source/src_abcdefghijklmnop/in/token1234567` and your provider makes a request to `https://api.svix.com/ingest/api/v1/source/src_abcdefghijklmnop/in/token1234567/foo/bar/baz?qux=duck`, `transformationsParams.headers["svix-ingest-query"]` will contain the string `qux=duck` and `transformationsParams.headers["svix-ingest-trailing-path-segments"]` will contain the string `foo/bar/baz`.