Skip to content

Commit a0cfd74

Browse files
authored
Add proper docs for Advanced Endpoints > Object Storage (#241)
This is basically a rephrase of what we have in https://docs.svix.com/stream/sinks/s3, but using webhooks vocabulary and generalizing over all object storage sinks. Preview at https://svix-docs-git-lucho-os-docs-advendp-svix.vercel.app/advanced-endpoints/object-storage Closes svix/monorepo-private#11402
1 parent 37858ce commit a0cfd74

File tree

1 file changed

+64
-1
lines changed

1 file changed

+64
-1
lines changed

docs/advanced-endpoints/object-storage.mdx

Lines changed: 64 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,4 +14,67 @@ When **Advanced Endpoint Types** is [enabled](/advanced-endpoints/intro#enabling
1414

1515
They will be able to configure the connection right in the App Portal.
1616

17-
![Object Storage Endpoint Create](../img/advanced-endpoints/s3-configuration.png)
17+
![Object Storage Endpoint Create](../img/advanced-endpoints/s3-configuration.png)
18+
19+
## Usage
20+
21+
By default, all Object Storage Endpoints come bundled with the following transformation code.
22+
23+
```JavaScript
24+
/**
25+
* @param input - The input object
26+
* @param input.events - The array of events in the batch. The number of events in the batch is capped by the Object Storage Endpoint's batch size.
27+
* @param input.events[].payload - The message payload (string or JSON)
28+
* @param input.events[].eventType - The message event type (string)
29+
*
30+
* @returns Object describing what will be put to the bucket.
31+
* @returns returns.config
32+
* @returns returns.config.format - The format of the request object put to the bucket. Valid values are "jsonl", "json", or "raw" (Defaults to jsonl).
33+
* @returns returns.config.key - The name of the object that will be put to the bucket. This will be suffixed with a timestamp to avoid duplicate object names.
34+
* @returns returns.data - The array of events to send to the bucket. This will be formatted according to the format.
35+
*/
36+
function handler(input) {
37+
return {
38+
config: {
39+
format: "jsonl",
40+
key: "object-generated-by-svix"
41+
},
42+
data: input.events
43+
}
44+
}
45+
```
46+
47+
`input.events` is the list of webhooks received by the endpoint, processed in batches.
48+
49+
`config` describes the object put in the destination - the key name of the object, and the format of the object saved to the bucket.
50+
51+
By default, the actual object key is always suffixed with a timestamp after the transformations are run. This ensures each event batch is saved as a unique object in the bucket.
52+
53+
For example, if the endpoint receives the following events:
54+
55+
```json
56+
{
57+
"eventType": "user.created",
58+
"payload": "{\"email\": \"joe@enterprise.io\"}"
59+
}
60+
```
61+
62+
```json
63+
{
64+
"eventType": "user.login",
65+
"payload": "{\"id\": 12, \"timestamp\": \"2025-07-21T14:23:17.861Z\"}"
66+
}
67+
```
68+
69+
The default transformation code would result in the following object being uploaded to the bucket.
70+
71+
![s3-recent-events](../img/stream/s3-example.png)
72+
73+
And the files contents would match the jsonl format.
74+
75+
```jsonl
76+
{"payload":{"email":"joe@enterprise.io"},"eventType":"user.created"}
77+
{"payload":{"id":12,"timestamp":"2025-07-21T14:23:17.861Z"},"eventType":"user.login"}
78+
```
79+
80+
If you want to control the format of the object more precisely, you can use `config.format = "raw"`, and set `data` to a string of the exact file contents you want.

0 commit comments

Comments
 (0)