7 |
8 | Documentation for the Svix libraries and CLI tool
9 |
10 | [](https://www.svix.com/slack/)
11 |
12 | # Documentation
13 |
14 | The docs are deployed to https://docs.svix.com
15 |
16 | ## Installation
17 |
18 | ```console
19 | yarn install
20 | ```
21 |
22 | ## Local Development
23 |
24 | ```console
25 | yarn start
26 | ```
27 |
--------------------------------------------------------------------------------
/babel.config.js:
--------------------------------------------------------------------------------
1 | module.exports = {
2 | presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
3 | };
4 |
--------------------------------------------------------------------------------
/blog/2019-05-28-hola.md:
--------------------------------------------------------------------------------
1 | ---
2 | slug: hola
3 | title: Hola
4 | author: Gao Wei
5 | author_title: Docusaurus Core Team
6 | author_url: https://github.com/wgao19
7 | author_image_url: https://avatars1.githubusercontent.com/u/2055384?v=4
8 | tags: [hola, docusaurus]
9 | ---
10 |
11 | Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet
12 |
--------------------------------------------------------------------------------
/blog/2019-05-29-hello-world.md:
--------------------------------------------------------------------------------
1 | ---
2 | slug: hello-world
3 | title: Hello
4 | author: Endilie Yacop Sucipto
5 | author_title: Maintainer of Docusaurus
6 | author_url: https://github.com/endiliey
7 | author_image_url: https://avatars1.githubusercontent.com/u/17883920?s=460&v=4
8 | tags: [hello, docusaurus]
9 | ---
10 |
11 | Welcome to this blog. This blog is created with [**Docusaurus 2 alpha**](https://v2.docusaurus.io/).
12 |
13 |
14 |
15 | This is a test post.
16 |
17 | A whole bunch of other information.
18 |
--------------------------------------------------------------------------------
/blog/2019-05-30-welcome.md:
--------------------------------------------------------------------------------
1 | ---
2 | slug: welcome
3 | title: Welcome
4 | author: Yangshun Tay
5 | author_title: Front End Engineer @ Facebook
6 | author_url: https://github.com/yangshun
7 | author_image_url: https://avatars0.githubusercontent.com/u/1315101?s=400&v=4
8 | tags: [facebook, hello, docusaurus]
9 | ---
10 |
11 | Blog features are powered by the blog plugin. Simply add files to the `blog` directory. It supports tags as well!
12 |
13 | Delete the whole directory if you don't want the blog features. As simple as that!
14 |
--------------------------------------------------------------------------------
/docs/account/environments.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: Managing Environments
3 | ---
4 |
5 | This section explains how to add and use multiple environments (e.g. dev, staging, and prod) from the same account.
6 |
7 | ## What are environments
8 |
9 | It's common practice for engineering teams to have multiple environments, such as development, staging, and production. The idea behind having multiple environments is to be able to test changes in isolation and catch issues before they hit production. So for example, a developer may make some changes locally, test them, and push them for testing in CI/CD. Following that, the change will be moved to a shared `development` environment where it would be tested by the wider team. Changes that pass this level of testing will move to `staging`, where they are deployed to an environment that's as similar as possible to the `production` environment, and after all testing pass there they would be deployed to `production` and rolled out to users.
10 |
11 | Not all teams go through all of the steps above (and some go through more), but the idea remains the same: you want to isolate your `production` environment, where real user data lies, from your non-production environments that may contain bugs and regressions.
12 |
13 | ## Managing environments
14 |
15 | Your Svix environments are completely isolated and have separate data, settings, and API keys.
16 |
17 | You can create as many environments as you want from the [Environment Management page](https://dashboard.svix.com/environments) on the dashboard.
18 |
19 | ### Add environments
20 |
21 | Click on `New Environment`, choose a name, mark the environment as either `Development` or `Production`, and choose the wanted region.
22 |
23 | 
24 |
25 | Development and production environments function identically; however, you will only be able to preview the App Portal for your development environments.
26 |
27 | 
28 |
29 | ### View environments
30 |
31 | This is how it looks like after adding multiple environments:
32 |
33 | 
34 |
35 | You can then switch between the active environment using the switcher on the top left corner and just start using that environment like you used your account before.
36 |
37 | ### Environment-specific settings
38 |
39 | When configuring your environments, it's important to know which settings are shared across your environments and which are kept separate. On the settings page, there is a separate section for "environment-specific" settings.
40 |
41 | 
42 |
43 | #### App Portal White Labeling
44 |
45 | The App Portal [White Labeling](../app-portal#white-labeling) is configured separately for each environment. This allows you to experiment with how the App Portal will look in your development environment without affecting your production users.
46 |
47 | #### HTTPS Only Endpoints
48 |
49 | It is strongly recommended that all registered endpoints in production environments are secured with HTTPS. If you want to allow unsecure endpoints (HTTP) on any environment, you may do so on the "General Settings" page.
50 |
51 | As of October 1st, 2021, HTTPS Only Endpoints is enabled by default on newly created environments. If your environment was created before then, the default was disabled and your environment was left unchanged.
52 |
53 |
54 | ## Environment import & export
55 |
56 | Import and export makes it very easy to clone (or sync) environments, and thus make sure that your staging and production environments are identical. It also makes it possible to save your environment settings in version control in order to make sure you keep track of changes to your environment.
57 |
58 | Export currently supports the environment settings as well as all of the event types. To import and export, all you need to do is to go to the [environment management](https://dashboard.svix.com/environments) page on the dashboard, choose the wanted environment from the list, and then click either import or export.
59 |
60 | 
61 |
--------------------------------------------------------------------------------
/docs/account/environments/env-add.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/account/environments/env-add.png
--------------------------------------------------------------------------------
/docs/account/environments/env-manage.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/account/environments/env-manage.png
--------------------------------------------------------------------------------
/docs/account/org-members.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: Managing Member Access
3 | ---
4 |
5 | This section explains how to manage access to your organization's account. You can easily give your teammates access, manage it, and invite new team members.
6 |
7 | ## Managing members
8 |
9 | There are currently four supported roles: `Viewer`, `Support Agent`, `Member` and `Admin`.
10 | - A `Viewer` has basic privileges and can view statistics and basic configurations but can't access API keys.
11 | - A `Support Agent` can preview [Consumer App Portals](../app-portal), in addition to having the same permissions as a `Viewer`.
12 | - A `Member` can control most aspects of the account, including applications, endpoints and event types.
13 | - An `Admin` can do all of that, and also manage members.
14 |
15 | You can invite as many members as you want to your organization, so feel free to invite all of your team. To do it, go to the [organization members page](https://dashboard.svix.com/settings/organization-group/members) on the dashboard.
16 |
17 | ### Invite a user
18 |
19 | Click on `Invite Teammates`, put in the email address of the teammate you would like to invite, and choose the appropriate role.
20 |
21 | 
22 |
23 | Svix will then send an invitation to the provided email address.
24 |
25 | ### Accept an invitation
26 |
27 | Once your teammate receives the invitation via email, they can follow the link to decide whether to accept or decline the invitation. Accepting the invitation will remove the recipient from their current account and add them to the new account. Declining the invitation will expire it.
28 |
29 | The recipient's email must be verified before they can accept an invitation.
30 |
31 | ### View members
32 |
33 | This is how it looks like after you've sent some invitations:
34 |
35 | 
36 |
37 | You can then add more members, manage access and manage invitations directly from this page.
38 |
--------------------------------------------------------------------------------
/docs/account/org-members/add-member.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/account/org-members/add-member.png
--------------------------------------------------------------------------------
/docs/account/org-members/manage-members.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/account/org-members/manage-members.png
--------------------------------------------------------------------------------
/docs/advanced-endpoints/fifo-endpoints.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: FIFO Endpoints
3 | ---
4 |
5 | # FIFO Endpoints
6 |
7 | FIFO endpoints let your webhook consumers receive webhooks in strict FIFO ordering (first in first out), unlike regular webhooks, which are delivered independently and order is on a best effort basis.
8 |
9 | Svix supports sending webhooks to both FIFO and regular endpoints, with no code changes required on your end.
10 |
11 | :::info[Why not make all webhooks FIFO?]
12 | Ensuring strict FIFO ordering comes with some tradeoffs. Since every call to the receiver endpoint is blocked until the previous one is successful, throughput is limited compared to regular webhook endpoints.
13 |
14 | Read more about [how FIFO endpoints work](https://www.svix.com/blog/fifo-ordered-webhooks-delivery/) and [the challenges with guaranteeing webhook ordering](https://www.svix.com/blog/guaranteeing-webhook-ordering/).
15 | :::
16 |
17 |
18 | ## Enabling FIFO Endpoints
19 | FIFO Endpoints can be enabled at the environment level in the [Svix Dashboard](https://dashboard.svix.com/settings/organization/general-settings) by enabling **Advanced Endpoint Types**.
20 |
21 | 
22 |
23 |
24 | When you enable FIFO Endpoints, your users will be able to create them in the [App Portal](/app-portal).
25 |
26 | 
27 |
28 | ## Message Batching
29 | Because of the strict ordering, Svix has to wait for a successful acknowledgement of delivery before sending any other messages. To address throughput constraints FIFO endpoints deliver webhooks in configurable batch sizes.
30 |
31 | The batching parameters can be configured in the [App Portal](/app-portal) for each endpoint.
32 |
33 | 
34 |
35 | ## Transformations
36 | [Transformations](/transformations) are also supported on FIFO endpoints. For FIFO endpoints, transformations are applied to each batch of messages.
37 |
38 | ### How to write a FIFO endpoint transformation
39 | Svix expects a Transformation to declare a function named `handler`. Svix will pass a `InputObject` to this function as its only argument, and expects the function to always return an `OutObject`.
40 |
41 | `InputObject` is a JSON object containing one property:
42 |
43 | - `events`, an array of objects containing `payload` and `eventType` properties. There is one element in the array for each message in the batch.
44 |
45 | `OutObject` is a JSON object containing one property:
46 |
47 | - `requestBody`, a string with the raw request body to be sent to the endpoint.
48 |
49 | ### An example Transformation
50 |
51 | You can write a transformation that transforms certain messages in the batch and forwards them.
52 |
53 | ```js
54 | function handler(input) {
55 | const events = input.events.map((evt) => {
56 | if (evt.eventType === "user.created") {
57 | return {
58 | ...evt.payload,
59 | name: evt.payload.firstName + " " + evt.payload.lastName
60 | }
61 | }
62 | });
63 |
64 | return {
65 | requestBody: JSON.stringify({ data: events })
66 | }
67 | }
68 | ```
69 |
70 | Or you can write transformations that collect messages and returns a summarized response.
71 |
72 | ```js
73 | function handler(input) {
74 | const total = input.events.reduce((acc, evt) => {
75 | if (evt.eventType === "invoice.created") {
76 | return acc + evt.payload.amount;
77 | }
78 | return acc;
79 | }, 0);
80 |
81 | return {
82 | requestBody: JSON.stringify({ total })
83 | }
84 | }
85 | ```
--------------------------------------------------------------------------------
/docs/advanced-endpoints/intro.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: Advanced Endpoint Types
3 | ---
4 |
5 | # Advanced Endpoint Types
6 |
7 | Svix supports multiple types of endpoints in addition to regular webhook endpoints, to support different use cases.
8 |
9 | - [Polling Endpoints](/advanced-endpoints/polling-endpoints)
10 | - [FIFO Endpoints](/advanced-endpoints/fifo-endpoints)
11 | - [Object Storage](/advanced-endpoints/object-storage)
12 |
13 | ## Enabling Advanced Endpoint Types
14 |
15 | Advanced Endpoint Types can be enabled at the environment level in the [Svix Dashboard](https://dashboard.svix.com/settings/organization/general-settings).
16 |
17 | 
18 |
19 | When you enable Advanced Endpoint Types, your users will be able to create them in the [App Portal](/app-portal).
20 |
21 | 
22 |
--------------------------------------------------------------------------------
/docs/advanced-endpoints/object-storage.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: Object Storage
3 | ---
4 |
5 | # Object Storage Endpoints
6 |
7 | Svix supports sending messages directly to [AWS S3](https://aws.amazon.com/s3/), [Google Cloud Storage](https://cloud.google.com/storage) and [Azure Blob Storage](https://azure.microsoft.com/en-us/products/storage/blobs).
8 |
9 | This is useful for storing payloads in a cloud storage bucket without your customers having to set up any listener endpoint or write any glue code.
10 |
11 | When **Advanced Endpoint Types** is [enabled](/advanced-endpoints/intro#enabling-advanced-endpoint-types), your customers will see the option to use object storage destinations in the [App Portal](/app-portal).
12 |
13 | 
14 |
15 | They will be able to configure the connection right in the App Portal.
16 |
17 | 
--------------------------------------------------------------------------------
/docs/advanced-endpoints/polling-endpoints.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: Polling Endpoints
3 | ---
4 |
5 | # Polling Endpoints
6 |
7 | Polling Endpoints are a way for your users to get a stream of events by polling instead of listening to webhooks.
8 |
9 | ## When is polling better?
10 |
11 | There are a few examples where polling for events works better than webhooks.
12 |
13 | One example is when testing webhooks locally. It's much easier to poll for events than exposing a public HTTP endpoint (even with tools like [Svix Play](/play) or [ngrok](/integrations/ngrok)).
14 |
15 | Another example is when your users don't care about getting events in real-time and prefer getting them all at once at the end of a day. One place where this use-case comes up, is when your users need to store all events for compliance reasons. In that case batching and saving them all at once is easier and more cost efficient for them.
16 |
17 | ## Enabling Polling Endpoints
18 |
19 | Polling Endpoints can be enabled at the environment level in the [Svix Dashboard](https://dashboard.svix.com/settings/organization/general-settings) by enabling **Advanced Endpoint Types**.
20 |
21 | 
22 |
23 | When you enable Polling Endpoints, your users will be able to create them in the [App Portal](/app-portal).
24 |
25 | 
26 |
27 | ## Usage
28 | Like with webhook endpoints, Polling Endpoints support filtering messages by [event types](/event-types) and [channels](/channels).
29 |
30 | In the App Portal, event consumers will get a unique URL and an API key to iterate through the full list of events sent to their [Svix Application](/overview#consumer-applications) since the endpoint was created.
31 |
32 | When creating a Polling Endpoint, consumers will get a unique URL like `https://api.us.svix.com/api/v1/app/app_2mG6DgUaGlwCNdM5oRCUJec2kQC/poller/poll_59q`
33 |
34 | When first calling the endpoint, it will return an empty array and an iterator.
35 |
36 | ```json
37 | {
38 | "data": [],
39 | "iterator": "eyJvZmZzZXQiOi05MjIzMzcyMDM2ODU0Nzc1ODA4LCJhZnRlciI6bnVsbH0",
40 | "done": false
41 | }
42 | ```
43 |
44 | Then, using the iterator in the next call, they can iterate through the events and poll for new ones.
45 |
46 | ```bash
47 | curl \
48 | "https://api.us.svix.com/api/v1/app/app_2mG6DgUaGlwCNdM5oRCUJec2kQC/poller/poll_59q?iterator=eyJv..." \
49 | -H 'Accept: application/json' \
50 | -H 'Authorization: Bearer sk_poll_*****.eu'
51 | ```
52 |
53 | Messages will be returned in the order they were sent to Svix.
54 |
55 | ### Polling with a Server-tracked Iterator
56 |
57 | By polling with a **Consumer ID**, the server will track the client's progress as it iterates through the stream of
58 | messages.
59 |
60 | > Consumer IDs are arbitrary strings used by a client to self-identify.
61 | >
62 | > Note that Consumer IDs should be _unique per client_ and should not be shared. Put another way, Consumer IDs track
63 | > exclusive sequential access through the stream of messages.
64 | > Shared concurrent access through a given Consumer ID will result in errors as mutual clients drift in their positions
65 | > in the stream.
66 |
67 | Usage is the same, and still relies on sending the `iterator` parameter to move forward through the stream.
68 | Server tracking of the client's iterator is opt-in by adding a trailing `/consumer/CONSUMER_ID` to the Polling Endpoint
69 | URL.
70 |
71 | ```bash
72 | curl \
73 | "https://api.us.svix.com/api/v1/app/app_2mG6DgUaGlwCNdM5oRCUJec2kQC/poller/poll_59q/consumer/MY-CONSUMER-ID?iterator=eyJv..." \
74 | -H 'Accept: application/json' \
75 | -H 'Authorization: Bearer sk_poll_*****.eu'
76 | ```
77 |
78 | The big difference is the server "remembers" the last `iterator` used to make a request for the given Consumer ID
79 | such that subsequent requests _without a `iterator`_ will resume using that last seen value.
80 | This is useful for situations where a process may be interrupted and lose its place while polling.
81 |
82 | In summation, when using Consumer IDs you need to provide an `iterator` in order to move forward, but you don't have to
83 | worry about losing progress or starting over if you lose an iterator for any reason.
84 | Poll the stream using the Consumer ID, omitting the `iterator` parameter, and you'll pick up where you left off.
85 | At that stage, use the provided `iterator` given in the response to start moving forward again.
86 |
87 | ### Updating a Server-tracked Iterator with Seek
88 |
89 | The `iterator` persisted on the server side can be adjusted with the `seek` endpoint.
90 |
91 | ```bash
92 | curl \
93 | "https://api.us.svix.com/api/v1/app/app_2mG6DgUaGlwCNdM5oRCUJec2kQC/poller/poll_59q/consumer/MY-CONSUMER-ID/seek" \
94 | -H 'Accept: application/json' \
95 | -H 'Content-Type: application/json' \
96 | -H 'Authorization: Bearer sk_poll_*****.eu' \
97 | -d '{"after": "2025-01-17T00:00:00.0Z"}'
98 | ```
99 |
100 | Note that after performing a `seek`, active clients sending a now-out-of-sequence `iterator` may see errors.
101 | In this situation, omitting the `iterator` parameter (as if making a new "initial" request) will allow such clients
102 | to pick up from the position tracked by the server. Subsequent requests should then use the iterator value returned
103 | in each response body.
104 |
105 | ---
106 |
107 | Polling Endpoints can be used in parallel with regular Svix webhooks, and you don't need to make any changes to how you [create messages](/quickstart#send-a-message).
108 |
--------------------------------------------------------------------------------
/docs/api-keys.mdx:
--------------------------------------------------------------------------------
1 | # API keys
2 |
3 | Manage your API keys to authenticate requests with Svix.
4 | Svix authenticates your API requests using your account’s API keys. If you don’t include your key when making an API request, or use an incorrect or outdated one, Svix returns an error.
5 |
6 | **API keys are per environment.** Every organization starts with a development environment with a corresponding API key. This key should only be used for development or internal testing and is not intended to be used in any production systems.
7 |
8 | ## Obtaining your API keys
9 |
10 | Your API keys can be found on the "API Access" page of the Svix Dashboard.
11 |
12 | 
13 |
14 | ## Keeping your keys safe
15 |
16 | Your secret API key can be used to make any API call on behalf of your account. Treat your secret API key as you would any other password. Grant access only to those who need it. Ensure it is kept out of any version control system you may be using. Control access to your key using a password manager or secrets management service.
17 |
18 | ## Rotating keys
19 |
20 | Svix support creating multiple API keys per environment. This gives you a lot of flexibility when rotating keys. For example, you can create a new key, replace all instances of the old key, and then expire the old key for a zero downtime key rotation.
21 |
22 | When expiring keys, you can also define when you would like the key to expire. Either immediately, or at a later point in time.
23 |
--------------------------------------------------------------------------------
/docs/channels.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: Channels
3 | ---
4 |
5 | Channels are an extra dimension of filtering messages that is orthogonal to [event types](./event-types.mdx). You can listen to multiple channels from each endpoint, and you can send each message to multiple channels.
6 |
7 | Event types imply a specific consistent schema, and mean a specific type of message. Channels are filters based on the expected recipient or group of recipients.
8 |
9 | **Note:** like event types, channels are meant to filter messages to a particular application, and not across applications.
10 |
11 | ## How to use it
12 |
13 | You first need to enable support to it for each of your environments from [the dashboard](https://dashboard.svix.com/settings/organization/general-settings).
14 |
15 | Once enabled, your customers can choose their wanted channels from the Application Portal, or alternatively you can set it per endpoint in the API.
16 |
17 | 
18 |
19 | You then need to send messages with the corresponding channels in order for these to reach the endpoints that filter by them. See below for the channels filtering rules.
20 |
21 | ```typescript
22 | await svix.message.create('app_id', {
23 | eventType: "user.signup",
24 | channels: [
25 | "project_123",
26 | "project_group_11"
27 | ],
28 | payload: {
29 | "username": "test_user",
30 | "email": "test@example.com"
31 | },
32 | });
33 | ```
34 |
35 | ## When not to use it
36 |
37 | The channels are not meant as a way to filter messages across different customers, that's what applications are for. Applications provide proper isolation between messages of different customers, while channels do not. Additionally, while you can have an infinite number of applications, there's a limit to the number of endpoints per application (more on that [on the Endpoint API docs](https://api.svix.com/docs#tag/Endpoint)).
38 |
39 | Additionally, there are limits to the number of channels messages and endpoints can be associated with. And having applications with a large number of endpoints is very inefficient and can hurt performance.
40 |
41 | ## Example use-cases
42 |
43 | Channels are useful for when you have a variety of sub-categories or recipients that expect the same types of messages but just need additional filtering.
44 |
45 | For example, consider Github. You may want to define webhooks for the whole organization, but only send certain events to certain endpoints based on the repository. You could just create a Svix App per repository and then manually add the endpoints to each, but it makes for a much better experience to have the webhook handling defined in one place with the same endpoints listening to multiple projects.
46 |
47 | So for example, you can have `svix`, `svix/svix-webhooks` and `svix/svix-docs` as channels, and then have Github send messages for both `svix` and for each repo whenever an event occurs on a specific repository. Github's customers can then create endpoints that listen to events either for the whole group, or for each repository in particular.
48 |
49 | ## Channels filtering rules
50 |
51 | Channels are case-sensitive, and endpoints that are filtering for specific channels will only get messages sent to that specific channel.
52 |
53 | Svix will send (or not send) to endpoints based on the following conditions:
54 | 1. Endpoint has no channels set: this is a catch-all, all messages are sent to to it, regardless of whether the message had channels set.
55 | 2. Both endpoint and message have channels set: if there's a shared channel between them, the message will be sent to the endpoint.
56 | 3. Endpoint has channels set and message has *no* channels set: the message will not be sent to the endpoint.
57 |
--------------------------------------------------------------------------------
/docs/consuming-webhooks.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: Consuming Webhooks
3 | ---
4 |
5 | In addition to helping you send webhooks to your users, we also help your users to easily verify the authenticity and security of the webhooks they receive from you.
6 |
7 | :::info
8 | For information on how to verify webhooks, please head to the [Consuming Webhooks documentation](/receiving/introduction.mdx).
9 | :::
10 |
11 | ## Documentation for your users
12 |
13 | We offer easy to use docs for how to safely consume webhooks which you can share with your users directly: [Consuming Webhooks documentation](/receiving/introduction.mdx).
14 |
15 | ## Building your own libraries
16 |
17 | Depending on your product, you may want to offer additional processing before passing the verified payload for your customers. For example, you may want to create API objects from the payload that your users can use to interact with your API.
18 |
19 | In this scenario you would want to create your own `Webhook` class equivalent that uses the `Svix` class internally. This way you can get all of the verification that Svix offer, while still being able to post-process the payload before passing it to your users.
20 |
--------------------------------------------------------------------------------
/docs/endpoint-authentication.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: Advanced Endpoint Authentication
3 | ---
4 |
5 | Svix supports advanced endpoint authentication methods that can be used by your customers on top of the standard signature verification.
6 |
7 | :::info
8 | These are advanced methods that are not required to keep your webhooks secure, but your customers might need them for their use case.
9 | Read the [security docs](/security) for more information.
10 | :::
11 |
12 | ## Enabling OAuth and mTLS
13 |
14 | OAuth and mTLS can be enabled at the environment level in the [Svix Dashboard](https://dashboard.svix.com/settings/organization/general-settings).
15 |
16 | 
17 |
18 | When enabled, your users will see an option in the [App Portal](/app-portal) to configure the respective authentication method on their endpoints.
19 |
20 | 
21 |
22 | ## OAuth
23 | To configure OAuth, your users will need to enter a `Client ID` and the `Authorization Server URL`, as well as the rest of the OAuth parameters, depending on the desired `Grant type` and `Authentication method`.
24 |
25 | 
26 |
27 | ## Mutual TLS (mTLS)
28 |
29 | With mTLS, your users can upload a private PEM encoded private key and certificate, which will be used to sign the requests sent to the endpoint, and to verify the identity of the receiving server.
30 |
31 | 
32 |
33 | For self-signed certificates, a custom Certificate Authority certificate can also be specified.
34 |
--------------------------------------------------------------------------------
/docs/get-help.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: Get Help & Chat With Us
3 | ---
4 |
5 | We love chatting with developers!
6 |
7 | If anything is unclear, you have some feedback, or you would just like to chat please get in touch! You can join the community on [our Slack](https://www.svix.com/slack/) or reach out via email at contact@svix.com. We are also happy to jump on a call, so just drop us a line.
8 |
9 | [](https://www.svix.com/slack/)
10 |
--------------------------------------------------------------------------------
/docs/idempotency.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: Idempotency
3 | ---
4 |
5 | import CodeTabs from "@theme/CodeTabs";
6 | import TabItem from "@theme/TabItem";
7 |
8 | Svix supports [idempotency](https://en.wikipedia.org/wiki/Idempotence) for safely retrying requests without accidentally performing the same operation twice. This is useful when an API call is disrupted in transit and you do not receive a response.
9 |
10 | To perform an idempotent request, pass the idempotency key in the `Idempotency-Key` header to the request. The idempotency key should be a unique value generated by the client. You can create the key in however way you like, though we suggest using UUID v4, or any other string with enough entropy to avoid collisions.
11 |
12 |
13 |
14 |
15 | ```js
16 | const svix = new Svix("AUTH_TOKEN");
17 | const message = {
18 | eventType: "invoice.paid",
19 | eventId: "evt_Wqb1k73rXprtTm7Qdlr38G",
20 | payload: {
21 | type: "invoice.paid",
22 | id: "invoice_WF7WtCLFFtd8ubcTgboSFNql",
23 | status: "paid",
24 | attempt: 2,
25 | },
26 | };
27 | await svix.message.create("app_Xzx8bQeOB1D1XEYmAJaRGoj0", message, {
28 | idempotencyKey: "fd56a56b-838d-4456-8b83-390802672895",
29 | });
30 | ```
31 |
32 |
33 |
34 |
35 | ```python
36 | svix = Svix("AUTH_TOKEN")
37 | message = MessageIn(
38 | event_type="invoice.paid",
39 | event_id="evt_Wqb1k73rXprtTm7Qdlr38G",
40 | payload={
41 | "type": "invoice.paid",
42 | "id": "invoice_WF7WtCLFFtd8ubcTgboSFNql",
43 | "status": "paid",
44 | "attempt": 2
45 | }
46 | )
47 | svix.message.create(
48 | "app_Xzx8bQeOB1D1XEYmAJaRGoj0",
49 | message,
50 | PostOptions(idempotency_key="fd56a56b-838d-4456-8b83-390802672895")
51 | )
52 | ```
53 |
54 |
55 |
56 |
57 | ```go
58 | svixClient := svix.New("AUTH_TOKEN", nil)
59 | eventId := "evt_Wqb1k73rXprtTm7Qdlr38G"
60 | message := svix.MessageIn{
61 | EventType: "invoice.paid",
62 | EventId: *svix.NullableString(&eventId),
63 | Payload: map[string]interface{}{
64 | "type": "invoice.paid",
65 | "id": "invoice_WF7WtCLFFtd8ubcTgboSFNql",
66 | "status": "paid",
67 | "attempt": 2,
68 | },
69 | }
70 | idempotencyKey := "fd56a56b-838d-4456-8b83-390802672895"
71 | svixClient.Message.CreateWithOptions(ctx, "app_Xzx8bQeOB1D1XEYmAJaRGoj0", &message, &svix.PostOptions{
72 | IdempotencyKey: &idempotencyKey,
73 | })
74 | ```
75 |
76 |
77 |
78 |
79 | ```rust
80 | let svix = Svix::new("AUTH_TOKEN".to_owned(), None);
81 | svix.message()
82 | .create(
83 | "app_Xzx8bQeOB1D1XEYmAJaRGoj0".to_owned(),
84 | MessageIn {
85 | event_type: "invoice.paid".to_owned(),
86 | event_id: Some("evt_Wqb1k73rXprtTm7Qdlr38G".to_owned()),
87 | payload: json!({
88 | "type": "invoice.paid",
89 | "id": "invoice_WF7WtCLFFtd8ubcTgboSFNql",
90 | "status": "paid",
91 | "attempt": 2
92 | }),
93 | ..MessageIn::default()
94 | },
95 | Some(PostOptions {
96 | idempotency_key: Some("fd56a56b-838d-4456-8b83-390802672895".to_owned()),
97 | }),
98 | )
99 | .await?;
100 | ```
101 |
102 |
103 |
104 |
105 | ```java
106 | Svix svix = new Svix("AUTH_TOKEN");
107 |
108 | MessageIn message = new MessageIn()
109 | .eventType("invoice.paid")
110 | .eventId("evt_Wqb1k73rXprtTm7Qdlr38G")
111 | .payload("{" +
112 | "\"type\": \"invoice.paid\"," +
113 | "\"id\": \"invoice_WF7WtCLFFtd8ubcTgboSFNql\"," +
114 | "\"status\": \"paid\"," +
115 | "\"attempt\": 2" +
116 | "}");
117 |
118 | PostOptions opts = new PostOptions()
119 | .idempotencyKey("fd56a56b-838d-4456-8b83-390802672895");
120 |
121 | svix.getMessage()
122 | .create("app_Xzx8bQeOB1D1XEYmAJaRGoj0", message, opts);
123 | ```
124 |
125 |
126 |
127 |
128 | ```kotlin
129 | val svix = Svix("AUTH_TOKEN")
130 | svix.message.create("app_Xzx8bQeOB1D1XEYmAJaRGoj0",
131 | MessageIn(
132 | eventType = "invoice.paid",
133 | payload = mapOf(
134 | "type" to "invoice.paid",
135 | "id" to "invoice_WF7WtCLFFtd8ubcTgboSFNql",
136 | "status" to "paid",
137 | "attempt" to 2
138 | ),
139 | eventId = "evt_Wqb1k73rXprtTm7Qdlr38G"),
140 | PostOptions(
141 | idempotencyKey = "fd56a56b-838d-4456-8b83-390802672895"))
142 | ```
143 |
144 |
145 |
146 |
147 | ```ruby
148 | svix = Svix::Client.new("AUTH_TOKEN")
149 | svix.message.create(
150 | "app_Xzx8bQeOB1D1XEYmAJaRGoj0",
151 | Svix::MessageIn.new({
152 | "event_type" => "invoice.paid",
153 | "payload" => {
154 | "type": "invoice.paid",
155 | "id" => "invoice_WF7WtCLFFtd8ubcTgboSFNql",
156 | "status" => "paid",
157 | "attempt" => 2
158 | },
159 | "event_id" => "evt_Wqb1k73rXprtTm7Qdlr38G"}),
160 | { "idempotency_key" => "fd56a56b-838d-4456-8b83-390802672895" })
161 | ```
162 |
163 |
164 |
165 |
166 | ```csharp
167 | var svix = new SvixClient("AUTH_TOKEN", new SvixOptions("https://api.us.svix.com"));
168 | var message = new MessageIn(
169 | eventType: "invoice.paid",
170 | payload: new {
171 | type = "invoice.paid",
172 | id = "invoice_WF7WtCLFFtd8ubcTgboSFNql",
173 | status = "paid",
174 | attempt = 2
175 | },
176 | eventId: "evt_Wqb1k73rXprtTm7Qdlr38G"
177 | );
178 | await svix.Message.CreateAsync(
179 | "app_Xzx8bQeOB1D1XEYmAJaRGoj0",
180 | message,
181 | null,
182 | "fd56a56b-838d-4456-8b83-390802672895"
183 | );
184 | ```
185 |
186 |
187 |
188 |
189 | ```
190 | Idempotency is not yet supported in the Svix CLI.
191 | ```
192 |
193 |
194 |
195 |
196 | ```shell
197 | curl "https://api.us.svix.com/api/v1/app/app_Xzx8bQeOB1D1XEYmAJaRGoj0/msg/" \
198 | -H "Accept: application/json" \
199 | -H "Content-Type: application/json" \
200 | -H "Authorization: Bearer AUTH_TOKEN" \
201 | -H "Idempotency-Key: fd56a56b-838d-4456-8b83-390802672895"
202 | -d '{ "eventType": "invoice.paid", "eventId": "evt_Wqb1k73rXprtTm7Qdlr38G", "payload": { "type": "event.type", "id": "invoice_WF7WtCLFFtd8ubcTgboSFNql", "status": "paid", "attempt": 2 } }'
203 | ```
204 |
205 |
206 |
207 |
208 | Svix's idempotency works by saving the resulting status code and body of the first request made for any given idempotency key for any successful request. Subsequent requests with the same key return the same result for a period of up to 12 hours.
209 |
210 | Please note that idempotency is only supported for `POST` requests.
211 |
--------------------------------------------------------------------------------
/docs/img/advanced-endpoints/advanced-endpoints-setting.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/advanced-endpoints/advanced-endpoints-setting.png
--------------------------------------------------------------------------------
/docs/img/advanced-endpoints/fifo-endpoint-batching.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/advanced-endpoints/fifo-endpoint-batching.png
--------------------------------------------------------------------------------
/docs/img/advanced-endpoints/fifo-endpoint-create.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/advanced-endpoints/fifo-endpoint-create.png
--------------------------------------------------------------------------------
/docs/img/advanced-endpoints/object-storage-endpoints.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/advanced-endpoints/object-storage-endpoints.png
--------------------------------------------------------------------------------
/docs/img/advanced-endpoints/polling-endpoint-create-key.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/advanced-endpoints/polling-endpoint-create-key.png
--------------------------------------------------------------------------------
/docs/img/advanced-endpoints/polling-endpoint-create.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/advanced-endpoints/polling-endpoint-create.png
--------------------------------------------------------------------------------
/docs/img/advanced-endpoints/polling-endpoint-details-create-key.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/advanced-endpoints/polling-endpoint-details-create-key.png
--------------------------------------------------------------------------------
/docs/img/advanced-endpoints/polling-endpoint-setting.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/advanced-endpoints/polling-endpoint-setting.png
--------------------------------------------------------------------------------
/docs/img/advanced-endpoints/s3-configuration.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/advanced-endpoints/s3-configuration.png
--------------------------------------------------------------------------------
/docs/img/api-access-page.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/api-access-page.png
--------------------------------------------------------------------------------
/docs/img/attempts.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/attempts.png
--------------------------------------------------------------------------------
/docs/img/channels.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/channels.png
--------------------------------------------------------------------------------
/docs/img/congratulations.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/congratulations.png
--------------------------------------------------------------------------------
/docs/img/connectors-endpoint.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/connectors-endpoint.png
--------------------------------------------------------------------------------
/docs/img/connectors-list.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/connectors-list.png
--------------------------------------------------------------------------------
/docs/img/connectors/connect-to-discord.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/connectors/connect-to-discord.png
--------------------------------------------------------------------------------
/docs/img/connectors/connect-to-hubspot.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/connectors/connect-to-hubspot.png
--------------------------------------------------------------------------------
/docs/img/connectors/connect-to-slack.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/connectors/connect-to-slack.png
--------------------------------------------------------------------------------
/docs/img/connectors/connect-to-teams.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/connectors/connect-to-teams.png
--------------------------------------------------------------------------------
/docs/img/connectors/connect-to-windmill.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/connectors/connect-to-windmill.png
--------------------------------------------------------------------------------
/docs/img/connectors/custom-integration.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/connectors/custom-integration.png
--------------------------------------------------------------------------------
/docs/img/connectors/logos/closecrm-icon.svg:
--------------------------------------------------------------------------------
1 |
17 |
--------------------------------------------------------------------------------
/docs/img/connectors/logos/customerio-icon.svg:
--------------------------------------------------------------------------------
1 |
--------------------------------------------------------------------------------
/docs/img/connectors/logos/discord-icon.svg:
--------------------------------------------------------------------------------
1 |
2 |
--------------------------------------------------------------------------------
/docs/img/connectors/logos/hubspot-icon.svg:
--------------------------------------------------------------------------------
1 |
--------------------------------------------------------------------------------
/docs/img/connectors/logos/inngest-icon.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/connectors/logos/inngest-icon.png
--------------------------------------------------------------------------------
/docs/img/connectors/logos/loops-icon.svg:
--------------------------------------------------------------------------------
1 |
2 |
6 |
--------------------------------------------------------------------------------
/docs/img/connectors/logos/microsoft-teams-icon.svg:
--------------------------------------------------------------------------------
1 |
--------------------------------------------------------------------------------
/docs/img/connectors/logos/resend-icon.svg:
--------------------------------------------------------------------------------
1 |
6 |
--------------------------------------------------------------------------------
/docs/img/connectors/logos/segment-icon.svg:
--------------------------------------------------------------------------------
1 |
2 |
--------------------------------------------------------------------------------
/docs/img/connectors/logos/sendgrid-icon.svg:
--------------------------------------------------------------------------------
1 |
2 |
--------------------------------------------------------------------------------
/docs/img/connectors/logos/slack-icon.svg:
--------------------------------------------------------------------------------
1 |
--------------------------------------------------------------------------------
/docs/img/connectors/logos/vercel-icon.svg:
--------------------------------------------------------------------------------
1 |
4 |
--------------------------------------------------------------------------------
/docs/img/connectors/logos/webhook-icon.svg:
--------------------------------------------------------------------------------
1 |
--------------------------------------------------------------------------------
/docs/img/connectors/logos/windmill-icon.svg:
--------------------------------------------------------------------------------
1 |
2 |
3 |
31 |
--------------------------------------------------------------------------------
/docs/img/connectors/logos/zapier-icon.svg:
--------------------------------------------------------------------------------
1 |
--------------------------------------------------------------------------------
/docs/img/dashboard-preview-button.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/dashboard-preview-button.png
--------------------------------------------------------------------------------
/docs/img/edit-transformation.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/edit-transformation.png
--------------------------------------------------------------------------------
/docs/img/embedded-management-ui.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/embedded-management-ui.png
--------------------------------------------------------------------------------
/docs/img/enable-transformations.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/enable-transformations.png
--------------------------------------------------------------------------------
/docs/img/endpoint-authentication/endpoint-authentication-configure.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/endpoint-authentication/endpoint-authentication-configure.png
--------------------------------------------------------------------------------
/docs/img/endpoint-authentication/endpoint-authentication-enable.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/endpoint-authentication/endpoint-authentication-enable.png
--------------------------------------------------------------------------------
/docs/img/endpoint-authentication/endpoint-configure-mtls.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/endpoint-authentication/endpoint-configure-mtls.png
--------------------------------------------------------------------------------
/docs/img/endpoint-authentication/endpoint-configure-oauth.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/endpoint-authentication/endpoint-configure-oauth.png
--------------------------------------------------------------------------------
/docs/img/env-specific-settings.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/env-specific-settings.png
--------------------------------------------------------------------------------
/docs/img/event-catalog-config.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/event-catalog-config.png
--------------------------------------------------------------------------------
/docs/img/event-catalog-published.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/event-catalog-published.png
--------------------------------------------------------------------------------
/docs/img/event-type-openapi.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/event-type-openapi.png
--------------------------------------------------------------------------------
/docs/img/event-type-selection.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/event-type-selection.png
--------------------------------------------------------------------------------
/docs/img/import-export.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/import-export.png
--------------------------------------------------------------------------------
/docs/img/ngrok-signing-key.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/ngrok-signing-key.png
--------------------------------------------------------------------------------
/docs/img/ngrok-webhook-provider.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/ngrok-webhook-provider.png
--------------------------------------------------------------------------------
/docs/img/opentelemetry-spans.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/opentelemetry-spans.png
--------------------------------------------------------------------------------
/docs/img/schema-add-code.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/schema-add-code.png
--------------------------------------------------------------------------------
/docs/img/schema-add-schema.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/schema-add-schema.png
--------------------------------------------------------------------------------
/docs/img/schema-editor-basic.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/schema-editor-basic.png
--------------------------------------------------------------------------------
/docs/img/schema-preview.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/schema-preview.png
--------------------------------------------------------------------------------
/docs/img/slack-portal-connect.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/slack-portal-connect.png
--------------------------------------------------------------------------------
/docs/img/slack-portal.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/slack-portal.png
--------------------------------------------------------------------------------
/docs/img/svix-play.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/svix-play.png
--------------------------------------------------------------------------------
/docs/img/transformations-card.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/transformations-card.png
--------------------------------------------------------------------------------
/docs/img/tutorials/slack-connectors/advanced-formatting.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/tutorials/slack-connectors/advanced-formatting.png
--------------------------------------------------------------------------------
/docs/img/tutorials/slack-connectors/new-endpoint.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/tutorials/slack-connectors/new-endpoint.png
--------------------------------------------------------------------------------
/docs/img/tutorials/slack-connectors/slack-notification.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/tutorials/slack-connectors/slack-notification.png
--------------------------------------------------------------------------------
/docs/img/tutorials/slack-connectors/testing.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/tutorials/slack-connectors/testing.png
--------------------------------------------------------------------------------
/docs/img/zap-creation-step-1.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/zap-creation-step-1.png
--------------------------------------------------------------------------------
/docs/img/zap-creation-step-2.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/zap-creation-step-2.png
--------------------------------------------------------------------------------
/docs/img/zap-creation-step-3.1.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/zap-creation-step-3.1.png
--------------------------------------------------------------------------------
/docs/img/zap-creation-step-3.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/zap-creation-step-3.png
--------------------------------------------------------------------------------
/docs/img/zap-creation-step-4.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/zap-creation-step-4.png
--------------------------------------------------------------------------------
/docs/img/zap-creation-step-5.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/zap-creation-step-5.png
--------------------------------------------------------------------------------
/docs/img/zapier-integration-generator.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/svix/svix-docs/dcf9a1586d90a7409cfef7087dec8a1edc4dba7b/docs/img/zapier-integration-generator.png
--------------------------------------------------------------------------------
/docs/incoming-webhooks.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: Operational Webhooks
3 | ---
4 |
5 | import EventTypeTabs from '@theme/EventTypeTags';
6 | import TabItem from '@theme/TabItem';
7 |
8 | In addition to enabling you to send webhooks to your customers, Svix also sends you webhooks about the events in your Svix environment. We call these: "Operational webhooks".
9 |
10 | These webhooks let you build powerful workflows and automations over events in your account. For example, a common one is to monitor for [`endpoint.disabled`](https://api.svix.com/docs#tag/Webhook/operation/endpoint.disabled), which triggers when an endpoint has been automatically disabled after multiple days of failing, and notify your customer automatically via email when that happens.
11 |
12 | To subscribe to operational webhooks, please head to the [Operational Webhooks](https://dashboard.svix.com/webhooks) section of the dashboard.
13 |
14 | For more information on the exact events, their schemas, and other related documentation please refer to the [the webhooks section](https://api.svix.com/docs#tag/Webhook) of the API reference documentation.
15 |
--------------------------------------------------------------------------------
/docs/integrations/advanced-zapier.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: Advanced Zapier Integrations
3 | ---
4 |
5 | [Zapier](https://zapier.com/) is an online automation tool that connects apps and services.
6 | You can build a Zapier integration that allows your customers to connect your service to other services with Svix.
7 |
8 | The Svix auto-generated Zapier integration is a Node/JavaScript project meaning it's defined as code and very easy to customize.
9 |
10 | This doc gives guidance on ways to enhance your Zapier webhook integration powered by Svix.
11 |
12 | :::info[Prerequisites]
13 | Before reading this doc, we strongly recommend reading the [Build a Zapier Integration](./zapier) docs.
14 | This doc assumes you're familiar with the basics of Svix Integrations and have a functional API key-based Zapier webhook integration.
15 | :::
16 |
17 | ## Upgrade an existing integration
18 |
19 | If you add or change your event types, you may want to upgrade your Zapier integration to a new auto-generated integration.
20 |
21 | ### Upgrading to an updated auto-generated package
22 |
23 | Follow the [Download the package](./zapier#download-the-package) section of the [Build a Zapier Integration](./zapier) guide to download an updated auto-generated package. Then follow the steps below to link the new package to the existing integration and deploy.
24 |
25 | #### Build and deploy
26 |
27 | After downloading and extracting the auto-generated integration package, download the package dependencies:
28 |
29 | ```
30 | npm install
31 | ```
32 |
33 | Then, link the new integration package to your existing Zapier integration using the Zapier CLI [link command](https://platform.zapier.com/cli_docs/cli#link):
34 | ```
35 | zapier link
36 | ```
37 |
38 | Finally, build & deploy the integration to Zapier through the [push command](https://platform.zapier.com/cli_docs/cli#push):
39 | ```
40 | zapier push
41 | ```
42 |
43 | ### Managing integration versions
44 |
45 | If you wish to version bump your integration, be sure to update your integration's `package.json` (shown below) to reflect the new version number. It defaults to `1.0.0`.
46 |
47 | ```json
48 | {
49 | "name": "zapier-webhook-integration-with-svix",
50 | "version": "1.0.0", // <------ CHANGE ME
51 | "main": "index.js",
52 | // << truncated >>
53 | }
54 | ```
55 |
56 | Zapier supports complex versioning use cases including migrating users during a version bump. Review the [Zapier Platform](https://platform.zapier.com/cli_docs/docs#deploying-an-app-version) docs for more information.
57 |
58 | ### Upgrading a customized integration
59 |
60 | If you have customized your integration package, you will need to manually reconcile the diff.
61 | We strongly recommend using version control like git to track the changes and aid in merging.
62 |
63 | ## Alternative authentication schemes
64 |
65 | By default, the auto-generated Zapier integration uses [custom (API key)](https://platform.zapier.com/cli_docs/docs#custom) authentication type and requires users to explicitly provide an application ID and integration key.
66 | The default scheme might be undesirable because it requires the user to copy-paste credentials and doesn't connect to your existing auth flows.
67 |
68 | To provide a better user experience that hides the Svix constructs, we recommend using [OAuth2](https://platform.zapier.com/cli_docs/docs#oauth2) or [Session](https://platform.zapier.com/cli_docs/docs#session) authentication. See the [Zapier Platform authentication](https://platform.zapier.com/cli_docs/docs#authentication) docs for more information.
69 | - With OAuth2, Zapier will redirect your user to your site where you can authenticate them and send Zapier back an access token. An demonstration of this flow's user experience is shown in the video below.
70 | - With Session Auth, Zapier will show a login form for your user to provide their username and password. Those are securely sent to your service where you'll send Zapier back a session token.
71 |
72 | With either authentication flow, you can make another request to your APIs to exchange the access/session token for the Svix application ID and integration key.
73 | An example of that API endpoint for a Flask-based service might look like the following:
74 |
75 | ```py
76 | svix = Svix("AUTH_TOKEN")
77 |
78 | @app.route('/webhook/integration/')
79 | @auth_required
80 | def get_svix_integration_key():
81 | app_id = ... # get your user's app id
82 | integration_out = svix.integration.create(app_id, IntegrationIn(
83 | name="Zapier Integration"
84 | ))
85 | ... # store your user's zapier integration ID
86 | key_out = svix.integration.get_key(app_id, integration_out.id)
87 | return jsonify({
88 | "application_id": app_id,
89 | "integration_key": key_out.key
90 | })
91 | ```
92 |
93 | #### OAuth2 Flow User Experience
94 |
95 |
96 |
98 |
99 |
100 | ## Custom triggers
101 |
102 | ### Multiple event types per trigger
103 |
104 | If you wish to configure triggers with multiple event types, you can modify the `filterTypes` field on the create endpoint operation during the trigger's subscribe hook.
105 |
106 | If you wish your users to specify a set of event types when creating the trigger, you can use Zapier's [input fields](https://platform.zapier.com/cli_docs/docs#input-fields) feature.
107 |
108 | ### Additional trigger fields
109 |
110 | By default, the auto-generated integration contains the example payload that you provided with the event type schema. Zapier supports explicitly defining the list of output fields for the trigger. If you have optional fields or multiple event types with different schemas, we recommend explicitly defining the [output fields](https://platform.zapier.com/cli_docs/docs#output-fields) on the trigger.
111 |
112 | ### Adding custom actions or triggers
113 |
114 | The auto-generated Zapier integration can be extended with additional actions, triggers, creates, or other Zapier resources. More information on this is available on the [Zapier CLI platform docs](https://platform.zapier.com/cli_docs/docs).
115 |
116 | The Zapier CLI can modify your package (e.g. creating a new action from a template). More information on that is available on the [Zapier CLI Reference](https://platform.zapier.com/cli_docs/cli).
117 |
--------------------------------------------------------------------------------
/docs/integrations/ngrok.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: Using the ngrok Integration
3 | ---
4 |
5 | [ngrok](https://ngrok.com) is a staple tool for many developers that creates tunnels between networks. It is often used to expose a port on localhost to the public Internet, but with ngrok Cloud Edge it can be also be used to secure traffic from the Internet to production cloud environments.
6 |
7 | In this tutorial, we will learn how to verify Svix webhook requests using ngrok both for local development and on ngrok Cloud Edge.
8 |
9 | :::info
10 | This tutorial assumes you are already familiar with the [Svix webhooks service](https://www.svix.com) and [ngrok](https://ngrok.com). If this is your first time using Svix,
11 | we recommend you first check out our [quickstart documentation](https://docs.svix.com/overview). We also recommend checking out ngrok's documentation on [Webhook Verification](https://ngrok.com/docs/http/webhook-verification/).
12 | :::
13 |
14 | ## Verify Svix webhooks locally with ngrok CLI
15 |
16 | ### Install ngrok
17 | If you haven't already, [install the ngrok CLI](https://ngrok.com/download).
18 |
19 | ### Create a tunnel
20 |
21 | First, create an endpoint in the Consumer App Portal, and copy the endpoint's Signing Signature. Then, run the following ngrok command on your computer's terminal, replacing SIGNATURE with the Signing Signature you just copied:
22 |
23 | ```sh
24 | ngrok http 3000 --verify-webhook=svix --verify-webhook-secret=SIGNATURE
25 | ```
26 |
27 | When you run the command, ngrok should generate URL that looks like `https://d7f4c8296c55.ngrok.io`. Copy that URL, and set it as the URL for the Svix endpoint you previously created in the Consumer App Portal.
28 |
29 | Assuming you are running a service on port 3000, all Svix webhooks to your endpoint will now be forwarded to that local service by ngrok. And because you configured the `--verify-webhook` and `--verify-webhook-secret` options, ngrok will only forward verified Svix webhooks.
30 |
31 | ## Verify Svix Webhooks on ngrok Cloud Edge
32 |
33 | ### Create a Svix endpoint
34 |
35 | Create an endpoint in the consumer application portal. You'll need the newly-created endpoint's Signing Signature later on.
36 |
37 | ### Sign up for ngrok
38 |
39 | Create an account on [ngrok.com](https://ngrok.com).
40 |
41 | ### Create an ngrok Edge
42 |
43 | Login to the [ngrok dashboard](https://dashboard.ngrok.com). Using the menu on the left, expand "Cloud Edge" and choose "Edges." Create an edge by clicking the "New edge" button and choose "HTTPS Edge".
44 |
45 | ### Configure ngrok Edge
46 |
47 | On the Edge configuration page, find and click the "Webhooks Verification" menu item, and click "Begin Setup." Choose Svix as your webhook provider:
48 |
49 | 
50 |
51 | And paste your endpoint's Signing Signature from Svix as the webhook signing key:
52 |
53 | 
54 |
--------------------------------------------------------------------------------
/docs/introduction.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: Introduction
3 | slug: /
4 | ---
5 |
6 | Svix makes sending webhooks easy and reliable by offering [webhook sending as a service](https://www.svix.com). With Svix you can start sending webhooks in minutes, while ensuring robust deliverability, and a great developer experience for your users.
7 |
8 | ## Webhooks are harder than they seem.
9 |
10 | Webhooks require a lot more engineering time, resources, and ongoing maintenance than you would first expect.
11 |
12 | When building your own webhooks you have to deal with a lot of challenges, such as: unreliable user endpoints, which fail or hang more often than you think; monitoring and reliability of your webhook system; security implications which are unique to webhooks and much more.
13 |
14 | This is where we come in. With Svix you can start sending webhooks in under five minutes, and we take care of all of the above and more.
15 |
--------------------------------------------------------------------------------
/docs/onboarding.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: Onboarding
3 | ---
4 |
5 | The onboarding document has now been merged with the rest of the documentation. In order to get started just navigate to the [main docs section](./introduction.mdx).
6 |
--------------------------------------------------------------------------------
/docs/opentelemetry-streaming.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: OpenTelemetry Streaming
3 | ---
4 |
5 | :::info[Important]
6 | OpenTelemetry streaming is only available as part of the Enterprise tier. Please refer to [the pricing page](https://www.svix.com/pricing/) for more information.
7 | Some of this functionality can also be achieved by using [Operational Webhooks](/incoming-webhooks).
8 | :::
9 |
10 | Svix offers OpenTelemetry streaming as a way to stream webhook delivery traces to observability platforms that support OpenTelemetry such as Datadog, Grafana, Coralogix, and most other observability platforms.
11 |
12 | ## What does Svix send
13 |
14 | Svix sends OpenTelemetry traces as two spans: the outer span `message_attempt` and the inner span `http_attempt`.
15 |
16 | Both spans include the following attributes:
17 | ```rust
18 | start: DateTime // Included as the span start time (not a field)
19 | end: DateTime // Included as the span end time (not a field)
20 | org_id: OrganizationId
21 | app_id: ApplicationId
22 | app_uid: Option
23 | endpoint_id: EndpointId
24 | msg_id: MessageId
25 | msg_event_id: Option
26 | event_type: EventTypeName,
27 | attempt_count: u16
28 | status: MessageStatus
29 | ```
30 |
31 | And the inner `http_attempt` also has:
32 | ```rust
33 | http.response.status_code: i16
34 | ```
35 |
36 | Here is an example of how it looks like in an observability dashboard:
37 |
38 | 
39 |
40 | ## How to use it
41 |
42 | The raw spans sent by Svix can be used in a variety of ways:
43 | * Deriving graphs and metrics for your observability dashboards.
44 | * Alerting for when specific customers fail over a certain threshold or their latency increases.
45 | * Storing raw delivery logs for compliance reasons.
46 | * Much more...
47 |
48 | For specific instructions on how to achieve the above, please refer to the documentation by your observability provider or [contact Svix support](https://www.svix.com/contact/).
49 |
--------------------------------------------------------------------------------
/docs/overview.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: Entities Overview
3 | ---
4 |
5 | This section provides an overview of the common Svix entities.
6 |
7 | The Svix entities are mostly hierarchical with the environment being the main isolation unit, below it there are applications which represent a target for messages, and even below there are endpoints which represent a destination to send webhooks to.
8 |
9 | 
10 |
11 |
12 | ## IDs and UIDs
13 |
14 | All Svix entities have IDs as their unique identifiers. Some entities, such as applications and endpoints, support an additional unique identifier called `UID`.
15 |
16 | These `UID`s can be used interchangeably with `ID`s all throughout the API. So for example, you can send a message to a specific `ID`, or a specific `UID`, both will work.
17 |
18 | This enables you to use Svix in a completely stateless manner, without having to store the Svix identifiers (or anything) in your own database.
19 |
20 |
21 |
22 | ## Consumer Applications
23 |
24 | When sending messages using the Svix API you will be sending them to a specific application (consumer), which will then distribute them to the associated endpoints.
25 | In most cases you would want to create one application for each of our customers, though in some cases you may want to create multiple applications per customer.
26 |
27 | Each application lies within its own security context. Each application is completely isolated from another, but also there is no isolation within an application. This means that you should assume that every message sent to an application can be viewed by all of the endpoints subscribed to that application. What does this mean in practice? Create different applications for different security contexts.
28 |
29 | You can define a `uid` for an application which can then be used interchangeably in the API with the application's `id`. Most people set the `uid` to their own internal customer id, so for example if they have a user called `some-user` they would set the `uid` to `some-user` and then use it with the Svix API as follows:
30 |
31 | ```javascript
32 | svix.application.update('some-user', ApplicationIn(/* ... */))
33 | ```
34 |
35 | It's recommended to create an application (using the API) for each of their customers when they sign up to your service. You can however also create it "lazily", and only do it when they enable webhooks.
36 |
37 | Alternatively, you can create an application the first time you send a message to it. When sending a message you can, optionally, send an `application` property along with it. If the application does not exist yet it will be created; if it does then the `application` property will be ignored.
38 |
39 | ```javascript
40 | svix.message.create('some-user', {
41 | application: ApplicationIn(/* ... */),
42 | payload: {/* ... */},
43 | })
44 | ```
45 |
46 |
47 | ## Endpoints
48 |
49 | Endpoints represent a target for messages sent to a specific application. You can have multiple endpoints per application, and every message sent to the application will be sent to all of them. Endpoints can have filters applied to them which will prevent them from receiving specific messages. The most common such filter is [event type](event-types.mdx), where an endpoint can choose to only subscribe to a limited set of events.
50 |
51 | Endpoints can be created by you using [the create endpoint API](https://api.svix.com/docs#operation/create_endpoint_api_v1_app__app_id__endpoint__post), though they are most commonly created by your customers using the [application portal](app-portal.mdx) or a similar UI.
52 |
53 | Like with applications, you can define a `uid` for an endpoint which can then be used interchangeably in the API with the endpoint's `id`.
54 |
55 |
56 | ## Messages
57 |
58 | Messages are the webhooks being sent. They can have a content, event type, and a few other properties.
59 |
60 | A message sent to an application will be sent to all of its endpoints (based on aforementioned filtering rules).
61 | When an application has no endpoints, or when no endpoints match a message, the sent message is just saved to the database but is not actually sent to a customer.
62 |
63 | If a message delivery fails, it will be attempted multiple times until either it succeeds, or its attempts have been exhausted. Please refer to the [retry schedule](retries.mdx) for more information.
64 |
65 | Messages can have an associated `eventId`. The `eventId` is used to map a message from Svix to one in your system so you can easily map a message to the reason why you sent it.
66 |
67 |
68 | ## Attempts
69 |
70 | Attempts represent an attempt that has been made to send a message to an endpoint. Attempts also record the response content of the attempt, the response HTTP status code, as well as other properties. Each attempt to send a message is recorded in an attempt entity which can then be queried (there can be multiple when there are failures).
71 |
72 |
73 | ## Event Types
74 |
75 | Event types are identifiers on messages that describe the message being sent and implies its associated schema. Each message has exactly one event type, and endpoints can listen to all, or a subset of the created event types.
76 |
77 | Event types schemas are used for things like "send example webhook" in the application portal, the event catalog, and the [automatic Zapier integration](integrations/zapier.mdx).
78 |
79 | You will need to create event types for them to be shown in the application portal and used by endpoints.
80 |
81 |
82 | ## Environments
83 |
84 | Environments are completely isolated Svix environments that have their own API keys, data, and settings. You can think of Svix environments are completely separate accounts.
85 |
86 | You can create as many environments as you want in the dashboard UI depending on your needs. Most people create one environment for `Production`, one for `Staging` and one for `Development`.
87 | Some people create multiple `Production` environments based on geographical regions e.g. `Production EU` and `Production US`.
88 |
--------------------------------------------------------------------------------
/docs/play.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: Svix Play - webhook debugger
3 | ---
4 |
5 | You can use the [Svix Play webhook playground and debugger](https://www.svix.com/play/) to easily inspect, test and debug operational webhooks.
6 |
7 | It's a very useful tool for anyone developing webhooks - for both senders and consumers. More so, it's available to everyone for free, not just users of Svix. No signup required!
8 |
9 | ## How to use
10 |
11 | To use Svix Play, just go to [play.svix.com](https://play.svix.com)
12 |
13 | You'll be redirected to the main Svix Play page, where you can copy your unique webhook URL and start sending it requests. Every request sent to this URL will respond with a successful `200 OK` response, and will be visible in the UI for you to inspect.
14 |
15 | This is how it looks like:
16 |
17 | 
18 |
19 | ## Relay mode (Svix CLI)
20 |
21 | In relay mode, you can use the Svix CLI for a free and secure public URL that relays requests to your local development server. All of these requests are then viewable in the [Svix Play webhook debugger](https://www.svix.com/play/) UI.
22 |
23 | All you have to do is install the [Svix CLI](https://github.com/svix/svix-cli) and run `svix listen` as shown here:
24 |
25 | ```
26 | $ svix listen http://localhost:8080/webhook/
27 |
28 | Webhook relay is now listening at
29 | https://play.svix.com/in/e_94XdF-OwN3EaTKty4izJDWRAH3V/
30 |
31 | All requests on this endpoint will be forwarded to your local URL:
32 | http://localhost:8080/webhook/
33 | ```
34 |
35 | ## Advanced usage
36 |
37 | ### Custom response codes
38 |
39 | Under normal usage, Svix Play (in echo mode) automatically returns successful responses to every request with the HTTP response code `200 OK`.
40 |
41 | However, in some cases you may want to check how your webhook system responds to failures. For example, does auto-retry work? Are errors properly handled?
42 |
43 | To enable that, Svix Play supports returning custom error codes by using the `force_status_code` query parameter when using our public API.
44 |
45 | For example, if your URL was:
46 |
47 | ```
48 | https://api.play.svix.com/api/v1/in/e_94XdF-OwN3EaTKty4izJDWRAH3V/
49 | ```
50 |
51 | You can change it to the following URL in order to make it always return `404 Not Found`:
52 |
53 | ```
54 | https://api.play.svix.com/api/v1/in/e_94XdF-OwN3EaTKty4izJDWRAH3V/?force_status_code=404
55 | ```
56 |
57 | ### Echo Request Bodies
58 |
59 | Under normal usage, Svix Play will return an empty body to every request towards an `/in/` route.
60 |
61 | If you wish to have the request body echoed back instead, set the `echo_body` query parameter to `true` when using our public API.
62 |
63 | For example, if your URL was:
64 |
65 | ```
66 | https://api.play.svix.com/api/v1/in/e_94XdF-OwN3EaTKty4izJDWRAH3V/
67 | ```
68 |
69 | You can change it to the following URL to make it respond with the same body it was given.
70 |
71 | ```
72 | https://api.play.svix.com/api/v1/in/e_94XdF-OwN3EaTKty4izJDWRAH3V/?echo_body=true
73 | ```
74 |
75 |
76 | ### Programmatic Use of the Public API
77 |
78 | To automatically test webhooks in your test suite, it is possible to use the public API to record dispatched webhooks and to see the history for a given token.
79 |
80 | You will need an echo token to start. These tokens are freely generated and are simply used to distinguish active sessions. These tokens are the same as you would see when visiting the Svix Play [web application](https://play.svix.com). Such a token may be easily generated programmatically with a POST request to the following route:
81 |
82 | ```
83 | https://api.play.svix.com/api/v1/token/generate/
84 | ```
85 |
86 | Next, send any number of events to the following route with any HTTP method:
87 |
88 | ```
89 | https://api.play.svix.com/api/v1/in/{your token here}/
90 | ```
91 |
92 | This route can take the query parameters `force_status_code`, `echo_body`, and `endpoint_signing_key`.
93 |
94 | Next, you'll want to analyze the record of events for this token using the `/history/` route as follows:
95 |
96 | ```
97 | https://api.play.svix.com/api/v1/history/{your token here}/
98 | ```
99 |
100 | The output of this route will look something like this:
101 |
102 | ```
103 | {
104 | "iterator": "2Nmzzn6O30LTlFwegZYjrIEuRPL",
105 | "data": [
106 | {
107 | "id": "2Nmzzn6O30LTlFwegZYjrIEuRPL",
108 | "url": "/api/v1/in/e_DCFOA2693TG8wtcRLDaD8aFOm3J/",
109 | "method": "GET",
110 | "created_at": "2023-03-31T17:38:29.921531707Z",
111 | "body": "",
112 | "headers": {
113 | "accept": "*/*",
114 | "user-agent": "curl/7.81.0"
115 | },
116 | "response": {
117 | "status_code": 204,
118 | "headers": {},
119 | "body": ""
120 | },
121 | "ip": null
122 | }
123 | ]
124 | }
125 | ```
126 |
127 |
128 | This route allows one query parameter, `iterator`. Given the `id` of one of the events sent, the history route will only return events that were received after that ID.
129 |
130 | For ease of use, the JSON object returned by the `/history/` route includes an `iterator` field which is set to the ID of the last received request, or the same iterator as given if no additional requests since then have been recorded.
131 |
132 | For example, if your URL was:
133 |
134 | ```
135 | https://api.play.svix.com/api/v1/history/e_94XdF-OwN3EaTKty4izJDWRAH3V/
136 | ```
137 |
138 | You can change it to the following URL in order to only display events that were received after the request with ID `2Nvo8F66yxe0cT7lrVmsbUg97He`:
139 |
140 | ```
141 | https://api.play.svix.com/api/v1/history/e_94XdF-OwN3EaTKty4izJDWRAH3V/?iterator=2Nvo8F66yxe0cT7lrVmsbUg97He
142 | ```
143 |
144 |
--------------------------------------------------------------------------------
/docs/rate-limit.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: Rate Limiting Endpoints
3 | ---
4 |
5 | import CodeTabs from '@theme/CodeTabs';
6 | import TabItem from '@theme/TabItem';
7 |
8 |
9 | While Svix can handle however many messages you send us, your customers' endpoints may not be able to. This is why the Svix API includes rate-limiting (throttling) calls to customer endpoints.
10 |
11 | This lets you send as many webhooks per second as you want without having to worry about overloading your customers' systems.
12 |
13 |
14 | ## How does it work?
15 |
16 | You can set a rate limit on both the application, which applies to all of the endpoints for that application, or the endpoint to only set it for that specific endpoint.
17 |
18 | The rate limit is defined as a limit for the number of messages per second to send to the endpoint. After the limit is reached, requests will get throttled so to keep a consistent rate under the limit.
19 |
20 | Due to the nature of distributed systems the actual rate of messages can sometimes be slightly above the enforce rate limit. So for example, if you set a rate limit of 1,000 per seconds, an endpoint may potentially get messages at a rate of 1,050 or even higher.
21 |
22 |
23 | ## Setting the limits
24 |
25 | You can set the rate limit on either the application or each of its endpoint. The rate limit is enforced per endpoint, so limits set on the application propagate to the endpoints and can be overridden by the endpoint specific settings.
26 |
27 | ### Setting application rate limits
28 |
29 | You can set the rate limit on an application when [creating](https://api.svix.com/docs#operation/create_application_api_v1_app__post) or [updating](https://api.svix.com/docs#operation/update_application_api_v1_app__app_id___put) it using the `rateLimit` property. The value is the number of messages per second.
30 |
31 |
32 |
33 |
34 | ```js
35 | import { Svix } from "svix";
36 |
37 | const svix = new Svix("AUTH_TOKEN");
38 | const app = await svix.application.create({name: "Application name", rateLimit: 1000});
39 | ```
40 |
41 |
42 |
43 |
44 | ```python
45 | from svix.api import Svix, ApplicationIn
46 |
47 | svix = Svix("AUTH_TOKEN")
48 | app = svix.application.create(ApplicationIn(name="Application name", rate_limit=1000))
49 | ```
50 |
51 |
52 |
53 |
54 | ```go
55 | import (
56 | svix "github.com/svix/svix-webhooks/go"
57 | )
58 |
59 | svixClient := svix.New("AUTH_TOKEN", nil)
60 | app, err := svixClient.Application.Create(ctx, &svix.ApplicationIn{
61 | Name: "Application name",
62 | RateLimit: 1000,
63 | })}
64 | ```
65 |
66 |
67 |
68 |
69 | ```rust
70 | use svix::api::{ApplicationIn, Svix, SvixOptions};
71 |
72 | let svix = Svix::new("AUTH_TOKEN".to_string(), None);
73 | let app = svix
74 | .application()
75 | .create(
76 | ApplicationIn {
77 | name: "Application name".to_string(),
78 | rate_limit: Some(1000),
79 | ..ApplicationIn::default()
80 | },
81 | None,
82 | )
83 | .await?;
84 | ```
85 |
86 |
87 |
88 |
89 | ```java
90 | import com.svix.models.ApplicationIn;
91 | import com.svix.models.ApplicationOut;
92 | import com.svix.Svix;
93 |
94 | Svix svix = new Svix("AUTH_TOKEN");
95 | ApplicationOut app = svix.getApplication().create(new ApplicationIn().name("Application name").rateLimit(1000));
96 | ```
97 |
98 |
99 |
100 |
101 | ```kotlin
102 | import com.svix.kotlin.models.ApplicationIn;
103 | import com.svix.kotlin.Svix;
104 |
105 | val svix = Svix("AUTH_TOKEN")
106 | val applicationOut = svix.application.create(ApplicationIn(
107 | name = "Application name",
108 | rateLimit = 1000))
109 | ```
110 |
111 |
112 |
113 |
114 | ```ruby
115 | require "svix"
116 |
117 | svix = Svix::Client.new("AUTH_TOKEN")
118 |
119 | application_out = svix.application.create(Svix::ApplicationIn.new({
120 | "name" => "Application name"
121 | "rate_limit" => 1000}))
122 | ```
123 |
124 |
125 |
126 |
127 | ```csharp
128 | using Svix;
129 | using Svix.Model;
130 | using Svix.Models;
131 |
132 | var svix = new SvixClient("AUTH_TOKEN", new SvixOptions("https://api.us.svix.com"));
133 | await svix.Application.CreateAsync(new EventTypeIn(
134 | name: "Application Name",
135 | rateLimit: 1000
136 | ))
137 | ```
138 |
139 |
140 |
141 |
142 | ```shell
143 | export SVIX_AUTH_TOKEN='AUTH_TOKEN'
144 | svix application create '{ "name": "Application name", "rateLimit": 1000 }'
145 | ```
146 |
147 |
148 |
149 |
150 | ```shell
151 | curl -X POST "https://api.us.svix.com/api/v1/app/" \
152 | -H "Accept: application/json" \
153 | -H "Content-Type: application/json" \
154 | -H "Authorization: Bearer AUTH_TOKEN" \
155 | -d '{"name": "Application name", "rateLimit": 1000}'
156 | ```
157 |
158 |
159 |
160 |
161 |
162 | ### Setting endpoint rate limits
163 |
164 | Similar to the application rate limiting, you can set the rate limit on an endpoint when [creating](https://api.svix.com/docs#operation/create_endpoint_api_v1_app__app_id__endpoint__post) or [updating](https://api.svix.com/docs#operation/update_endpoint_api_v1_app__app_id__endpoint__endpoint_id___put) it using the `rateLimit` property. The value is the number of messages per second.
165 |
166 |
167 | ## Intended use
168 |
169 | The rate limit is intended to be used as a sort of a fuse to protect your customers' servers from sudden peaks in message traffic that they may not be able to withstand. With the rate limiting, this peak is smoothened and spread over multiple seconds, sending messages at a rate your customers can handle.
170 |
171 | One important thing to remember with rate limiting, is that if you are limiting to 1,000 messages per second and are consistently sending messages over that limit (e.g. 2,000 per second), the queue will get congested and you will be sending messages with infinitely increasing delays. We can alert you of such issues, and help you address them when they occur, though this is still something to be mindful of.
172 |
--------------------------------------------------------------------------------
/docs/receiving/additional-authentication.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: Additional Authentication
3 | ---
4 |
5 | Svix [signs all webhooks](./verifying-payloads/why.mdx) in order to ensure the security and authenticity of all of the webhooks being sent.
6 |
7 | This security mechanism is already sufficient (and better) than other methods such as [HTTP Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication), and using an authentication token. However, some systems and IT departments have varying requirements for any HTTP request hitting their services (including webhooks), so Svix has built in support for these additional authentication modes.
8 |
9 | ## HTTP Basic Authentication
10 |
11 | HTTP Basic Authentication (Basic Auth), is a common way of sending a server a pair of username and password, or more often a username and auth token. While there are different ways of passing these credentials, the simplest and most common way is by including it as part of the URL.
12 |
13 | You can add it to the URL by prefixing the URL with the username and password (or token) and the @ symbol as such:
14 |
15 | ```
16 | https://USERNAME:PASSWORD@example.com/webhook/
17 | ```
18 |
19 | ## Header based authentication
20 |
21 | Some services require specific headers to be passed in order to be processed by their load balancers or application servers. These services often require a specific authentication token passed in the `Authorization` header, but sometimes there could also be different headers and values.
22 |
23 | Svix supports setting custom headers to be sent for each endpoint both [using the API](https://api.svix.com/docs#operation/update_endpoint_headers_api_v1_app__app_id__endpoint__endpoint_id__headers__put) and using [the application portal](./using-app-portal/adding-endpoints.mdx).
24 |
25 | ## Firewalls (IP blocking)
26 |
27 | Many, often larger, organizations have strict firewall rules for which IPs are allowed to send traffic to their systems. While this is not a very strong security mechanism on its own, it's often useful when used in conjunction with other methods (such as webhook signatures).
28 |
29 | In order to support these organizations and their requirements, Svix only sends webhooks requests from a specific set of IPs as detailed in the [source IP addresses section](./source-ips.mdx).
30 |
--------------------------------------------------------------------------------
/docs/receiving/introduction.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: Introduction
3 | ---
4 |
5 | Read to following sections to learn why and how to verify webhooks sent by the Svix service and its customers.
6 |
7 | :::tip
8 | You can use the [Svix Play webhook debugger](https://www.svix.com/play/) and the [Svix CLI](https://github.com/svix/svix-cli) to inspect, test and debug your webhooks during development.
9 | :::
10 |
11 | ## Webhooks Consumption 101
12 |
13 | Webhooks are how services notify each other of events. At their core they are just a `POST` request to a pre-determined endpoint. The endpoint can be whatever you want, and you can just [add them from the UI](/receiving/using-app-portal/adding-endpoints). You normally use one endpoint per service, and that endpoint listens to all of the event types. For example, if you receive webhooks from Acme Inc., you can structure your URL like: `https://www.example.com/acme/webhooks/`.
14 |
15 | The way to indicate that a webhook has been processed is by returning a `2xx` (status code `200-299`) response to the webhook message within a reasonable time-frame (15s with Svix). It's also important to disable `CSRF` protection for this endpoint if the framework you use enables them by default.
16 |
17 | Another important aspect of handling webhooks is to verify the signature and timestamp when processing them. You can learn more about it in the [why verify section](/receiving/verifying-payloads/why).
18 |
--------------------------------------------------------------------------------
/docs/receiving/receiving-with-ingest.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: Receiving Webhooks with Ingest
3 | ---
4 |
5 | import CodeTabs from '@theme/CodeTabs';
6 | import TabItem from '@theme/TabItem';
7 |
8 | Receiving webhooks with [Svix Ingest] starts by creating a `Source`.
9 |
10 | A `Source` generates an endpoint you can share with a webhook provider as a
11 | destination for their webhooks.
12 |
13 | Ingest supports signature verification schemes and flows used by a variety of
14 | webhook providers. Supported values for a `Source`'s `type` include:
15 |
16 | - `beehiiv`
17 | - `brex`
18 | - `clerk`
19 | - `github`
20 | - `guesty`
21 | - `hubspot`
22 | - `incidentIo`
23 | - `lithic`
24 | - `nash`
25 | - `pleo`
26 | - `replicate`
27 | - `resend`
28 | - `safebase`
29 | - `sardine`
30 | - `segment`
31 | - `shopify`
32 | - `slack`
33 | - `stripe`
34 | - `stych`
35 | - `svix` (that's us!)
36 | - `zoom`
37 | - `adobeSign`
38 | - `docusign`
39 |
40 | Additionally there's the option to configure a `Source` as `genericWebhook` to
41 | skip performing signature verification. This is useful for providers that have
42 | no verification scheme and for providers whose verification scheme is not yet
43 | supported by Ingest.
44 |
45 | :::tip
46 | Let us know if your webhook provider isn't yet supported so we can add it!
47 | :::
48 |
49 |
50 | ## Create a Source
51 |
52 | Creating a `Source` from the [Ingest Dashboard]:
53 |
54 | 
55 |
56 |
57 |
58 |
59 | ```javascript
60 | const svix = new Svix("AUTH_TOKEN");
61 | const ingestSourceOut = await svix.ingest.source.create({
62 | name: "myGithubWebhook",
63 | uid: "unique-identifier",
64 | type: "github",
65 | config: {
66 | secret: "SECRET"
67 | },
68 | });
69 | ```
70 |
71 |
72 |
73 |
74 | ```python
75 | svix = Svix("AUTH_TOKEN")
76 | ingest_source_out = svix.ingest.source.create(IngestSourceIn(
77 | name="myGithubWebhook",
78 | uid="unique-identifier",
79 | type="github",
80 | config=GithubConfig(
81 | secret="SECRET"
82 | ),
83 | ))
84 | ```
85 |
86 |
87 |
88 |
89 | ```go
90 | svixClient := svix.New("AUTH_TOKEN", nil)
91 | ingestSourceOut, err := svixClient.Ingest.Source.Create(
92 | ctx,
93 | &IngestSourceIn{
94 | Name: "myGithubWebhook",
95 | Uid: "unique-identifier",
96 | Type: IngestSourceInTypeGithub,
97 | Config: GithubConfig{
98 | Secret: "SECRET",
99 | },
100 | },
101 | )
102 | ```
103 |
104 |
105 |
106 |
107 | ```kotlin
108 | val svix = Svix("AUTH_TOKEN")
109 | val ingestSourceOut = svix.ingest.source.create(IngestSourceIn(
110 | name = "myGithubWebhook",
111 | uid = "unique-identifier",
112 | config = IngestSourceInConfig.Github(GithubConfig(
113 | secret = "SECRET"
114 | )),
115 | ))
116 | ```
117 |
118 |
119 |
120 |
121 | ```java
122 | Svix svix = new Svix("AUTH_TOKEN");
123 | IngestSourceOut ingestSourceOut = svix
124 | .getIngest()
125 | .getSource()
126 | .create(new IngestSourceIn()
127 | .name("myGithubWebhook")
128 | .uid("unique-identifier")
129 | .config(new IngestSourceInConfig.Github(new GithubConfig()
130 | .secret("SECRET")
131 | ))
132 | );
133 | ```
134 |
135 |
136 |
137 |
138 | ```ruby
139 | svix = Svix::Client.new("AUTH_TOKEN")
140 | ingest_source_out = svix.ingest.source.create(Svix::IngestSourceIn.new({
141 | "name": "myGithubWebhook",
142 | "uid": "unique-identifier",
143 | "config": Svix::IngestSourceInConfig::Github.new({
144 | "secret": "SECRET"
145 | })
146 | }))
147 | ```
148 |
149 |
150 |
151 |
152 | ```rust
153 | let svix = Svix::new("AUTH_TOKEN".to_string(), None);
154 | let ingest_source_out = svix.ingest().source().create(
155 | IngestSourceIn {
156 | name: "myGithubWebhook".to_owned(),
157 | uid: Some("unique-identifier".to_owned()),
158 | config: IngestSourceInConfig::Github(GithubConfig {
159 | secret: "SECRET".to_owned(),
160 | ..Default::default()
161 | }),
162 | ..Default::default()
163 | },
164 | None,
165 | ).await?;
166 | ```
167 |
168 |
169 |
170 |
171 | ```csharp
172 | var svix = new SvixClient("AUTH_TOKEN", new SvixOptions("https://api.us.svix.com"));
173 | var ingestSourceOut = await svix.Ingest.Source.CreateAsync(
174 | new IngestSourceIn{
175 | Name = "myGithubWebhook",
176 | Uid = "unique-identifier",
177 | Config = IngestSourceInConfig.Github(new GithubConfig {
178 | Secret = "SECRET",
179 | }),
180 | }
181 | );
182 | ```
183 |
184 |
185 |
186 |
187 | ```shell
188 | svix ingest source create '{
189 | "name": "myGithubWebhook",
190 | "uid": "unique-identifier",
191 | "type": "github",
192 | "config": {
193 | "secret": "SECRET"
194 | }
195 | }'
196 | ```
197 |
198 |
199 |
200 |
201 | ```shell
202 | curl -X 'POST' \
203 | 'https://api.eu.svix.com/ingest/api/v1/source' \
204 | -H 'Authorization: Bearer AUTH_TOKEN' \
205 | -H 'Accept: application/json' \
206 | -H 'Content-Type: application/json' \
207 | -d '{
208 | "name": "myGithubWebhook",
209 | "uid": "unique-identifier",
210 | "type": "github",
211 | "config": {
212 | "secret": "SECRET"
213 | }
214 | }'
215 | ```
216 |
217 |
218 |
219 |
220 | ## Tell your provider where to send webhooks
221 |
222 | The Ingest URL is also listed on the [Ingest Dashboard] for each `Source`.
223 |
224 | The `IngestSourceOut` response from the API will include an `ingestUrl` which is
225 | the endpoint you give to your provider, telling them where to send their
226 | webhooks.
227 |
228 | For GitHub, as is used in this example, this is referred to as the
229 | _"Payload URL"_.
230 |
231 |
232 | ## Managing incoming messages
233 |
234 | In the [Ingest Dashboard], the Destinations tab for your `Source` is where you
235 | can configure endpoints, view logs, inspect message payloads, etc.
236 |
237 | 
238 |
239 | Configuring endpoints allows you to forward messages received by Ingest over to
240 | the endpoints you choose using Svix Core.
241 |
242 | 
243 |
244 | Logs and statistics are available to help monitor for problems, replay or
245 | recover messages.
246 |
247 |
248 | ## Managing Source Tokens
249 |
250 | The last portion of the Ingest URL is a `Token` which can be
251 | invalidated and rotated:
252 |
253 | 
254 |
255 | `Token`s that are rotated stay usable for 24 hours. During this time both the
256 | old and new `Token`s are honored by Ingest. During this period it's important
257 | that you reconfigure your provider with the new Ingest URL in order to have a
258 | seamless transition.
259 |
260 | [Svix Ingest]: https://svix.com/ingest
261 | [Ingest Dashboard]: https://dashboard.svix.com/ingest
262 |
--------------------------------------------------------------------------------
/docs/receiving/source-ips.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: Static Source IP Addresses
3 | ---
4 |
5 | import sourceIps from "/static/webhook-ips.json";
6 |
7 | In case your webhook receiving endpoint is behind a firewall or NAT, you may need to allow traffic from Svix's static IP addresses.
8 |
9 | This is the full list of IP addresses that webhooks may originate from grouped by the region of the sender. The list is also available as a JSON file: [webhooks-ips.json](pathname:///webhook-ips.json).
10 |
11 | ## Regions
12 |
13 | The list of IP addresses below is grouped by the respective Svix region. The region where webhooks are sent from is the same as the region of respective environment. This means that all webhooks in the EU region will use the EU IP addresses below, all webhooks in the US region will use the US IP addressed below, and the same for every other region.
14 |
15 | ### US
16 |
17 |
62 |
63 | :::info[Important]
64 | Static source IPs are not guaranteed for all pricing tiers, please refer to [the pricing page](https://www.svix.com/pricing/) for more information.
65 | :::
66 |
67 | ## Webhook User Agent
68 |
69 | Some systems may require to identify the User-Agent used by Svix in addition to the IP addresses. Requests from the Svix service, as well as self-hosted instances, may use different user-agent strings depending on the exact plan and configuration (usually `Svix-Webhooks/{server-version}` or `Webhooks/{server-version}`).
70 |
71 | However, every webhook coming from the Svix hosted service (using the IP addresses above), will also include `sender-9YMgn` in order to enable easy identification of requests coming from the hosted service.
72 |
--------------------------------------------------------------------------------
/docs/receiving/using-app-portal/adding-endpoints.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: Adding Endpoints
3 | ---
4 |
5 | In order to start listening to messages sent through Svix, you will need to configure your **endpoints**.
6 |
7 | Adding an endpoint is as simple as providing a URL that you control and a list of **event types** that you want to
8 | listen to.
9 |
10 | 
11 |
12 | :::tip[Svix Play]
13 |
14 | If you don't have a URL or your service isn't quite ready to start receiving events just yet,
15 | just press the **use Svix Play** button to have a unique URL generated for you.
16 |
17 | You'll be able to view and inspect all operational webhooks sent to your Svix Play URL, making it
18 | effortless to get started.
19 | :::
20 |
21 | When configuring your endpoint, make sure to take a look at the [Event Catalog](./event-catalog) to see the
22 | full descriptions of each endpoint as well as all the fields they send.
23 |
24 | If you don't specify any event types, by default, your endpoint will receive all events, regardless of type.
25 | This can be helpful for getting started and for testing, but we recommend changing this to a subset later on
26 | to avoid receiving unexpected messages.
27 |
--------------------------------------------------------------------------------
/docs/receiving/using-app-portal/event-catalog.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: Event Catalog
3 | ---
4 |
5 | The Event Catalog shows all the **event types** available to subscribe to.
6 |
7 | 
8 |
9 | From here, you can view the **event definition**–the shape of the event payload
10 | as well as what values you can expect to receive.
11 |
12 | In addition, you can see an example payload for that event type.
13 |
--------------------------------------------------------------------------------
/docs/receiving/using-app-portal/filtering-logs.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: Filtering Logs
3 | ---
4 |
5 | 
6 |
7 | If you need to track down a particular message that was sent to one of your
8 | endpoints, there are a few ways to help you find it.
9 |
10 | If you know what endpoint it went to, the **endpoint page** has a filtered
11 | list of all messages sent to it. You can filter this list by
12 | **event type**. If you know roughly when the message was sent, you can further
13 | narrow down the list using the **date filter**.
14 |
15 | 
16 |
17 | You can choose to filter from one of the presets:
18 |
19 | - 5 hours ago
20 | - yesterday
21 | - last week
22 | - last month
23 | - custom
24 |
25 | If you choose "custom", you can specify an exact date and time to jump back to
26 | in the message list.
27 |
--------------------------------------------------------------------------------
/docs/receiving/using-app-portal/polling-endpoints.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: Polling Endpoints
3 | ---
4 |
5 | Polling Endpoints are a way to get a stream of events by polling, without having to set up a webhook endpoint.
6 |
7 | Start by creating an endpoint and select *Polling Endpoint* as the type.
8 |
9 | 
10 |
11 | As with [regular webhook endpoints](/receiving/using-app-portal/adding-endpoints), you can control which event types and channels you want to receive.
12 |
13 |
14 | # Usage
15 |
16 | Once you've created a Polling Endpoint, you'll get a unique URL like `https://api.us.svix.com/api/v1/app/app_2mG6DgUaGlwCNdM5oRCUJec2kQC/poller/poll_59q`.
17 |
18 | You can call this endpoint directly once you have an [API key](/receiving/using-app-portal/polling-endpoints#api-keys).
19 |
20 | ```bash
21 | curl \
22 | "https://api.us.svix.com/api/v1/app/app_2mG6DgUaGlwCNdM5oRCUJec2kQC/poller/poll_59q" \
23 | -H 'Accept: application/json' \
24 | -H 'Authorization: Bearer sk_poll_*****.eu'
25 | ```
26 |
27 | When first calling the endpoint, it will return an empty array and an iterator.
28 |
29 | ```json
30 | {
31 | "data": [],
32 | "iterator": "eyJvZmZzZXQiOi05MjIzMzcyMDM2ODU0Nzc1ODA4LCJhZnRlciI6bnVsbH0",
33 | "done": false
34 | }
35 | ```
36 |
37 | Then, using the iterator in the next call, you can iterate through the events and poll for new ones.
38 |
39 | ```bash
40 | curl \
41 | -X GET "https://api.us.svix.com/api/v1/app/app_2mG6DgUaGlwCNdM5oRCUJec2kQC/poller/poll_59q?iterator=eyJv..." \
42 | -H 'Accept: application/json' \
43 | -H 'Authorization: Bearer sk_poll_*****.eu'
44 | ```
45 |
46 | An example response might look like this:
47 |
48 | ```json
49 | {
50 | "data": [
51 | {
52 | "id": "ev_1234567890",
53 | "type": "invoice.created",
54 | "created_at": 1715289600
55 | },
56 | {
57 | "id": "ev_1234567891",
58 | "type": "invoice.updated",
59 | "created_at": 1715289601
60 | }
61 | ],
62 | "iterator": "aHR0cHM6Ly9hcGkuc3ZpeC5jb20vYXBpL3YxL2FwcC9hcHBfMm1HNkRnVWE=",
63 | "done": false
64 | }
65 | ```
66 |
67 | ### API Keys
68 |
69 | To call the Polling Endpoint, you'll need to create an endpoint-specific API key.
70 |
71 |
72 |
4 | .default})
79 | .default})
86 |