Ctrlk
CommunitySupport PortalYouTubeFree trialSign Up!
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Config

Retrieving a list of webhook configs

get

Retrieves a list of webhook configurations for a given tenant. A tenant can have at most one configuration per type: svix, svix_shared, and http.

Required scopes
This endpoint requires the following scopes:
  • : Needed to read subscriptions.
Authorizations
OAuth2clientCredentialsRequired
Token URL:
Path parameters
tenantstringRequired

Your Emporix tenant name.

Note: The tenant name should always be provided in lowercase.

Responses
200

Returning list of webhook configs.

application/json
activebooleanOptional

Indicates whether a given configuration is active. Only one configuration can be active at a time.

providerstring · enumOptional

Indicates which provider should be used.

Possible values:
codestringOptional

Unique identifier of the webhook configuration type.

configurationone ofOptional
get/webhook/{tenant}/config
GET /webhook/{tenant}/config HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

[
  {
    "code": "svix_shared",
    "provider": "SVIX_SHARED",
    "active": true
  },
  {
    "code": "svix",
    "provider": "SVIX",
    "active": false
  },
  {
    "code": "http",
    "provider": "HTTP",
    "active": false
  }
]

Creating a single webhook config

post

Creates a new webhook config for a given tenant. Currently the service supports the following webhook providers:

  • Svix Emporix Shared Account

  • Svix Custom Account

  • HTTP Webhook Strategy

NOTE At any time, a tenant can have only one webhook configuration of each type: svix, svix_shared, and http. If a configuration of the requested type already exists, the request returns a 409 Conflict response. To change the configuration, update or delete the existing one.

NOTE For HTTP configurations, eventsConfiguration can contain multiple entries for the same eventType. The server assigns a stable id to each entry. Omit id on create; client-supplied entry ids are rejected with 400. Each entry may include an optional JsonPath filter and optional excludedFields.

NOTE Svix supports a maximum message payload size of approximately 350kb. However, it is generally advisable to keep webhook payloads small, ideally under 40kb. For larger message sizes, consider using the HTTP Webhook Strategy.

Required scopes
This endpoint requires the following scopes:
  • : Needed to manage subscriptions.
Authorizations
OAuth2clientCredentialsRequired
Token URL:
Path parameters
tenantstringRequired

Your Emporix tenant name.

Note: The tenant name should always be provided in lowercase.

Body
activebooleanOptional

Indicates whether a given configuration is active. Only one configuration can be active at a time.

providerstring · enumRequired

Indicates which provider should be used.

Possible values:
configurationone ofOptional
object · EmptyConfigurationOptional

SVIX_SHARED config

or
or
codestringRequired

Unique identifier of the webhook configuration type.

Responses
201

Result of creating config

application/json
codestringOptional
post/webhook/{tenant}/config
POST /webhook/{tenant}/config HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 80

{
  "code": "svix_shared",
  "active": true,
  "provider": "SVIX_SHARED",
  "configuration": {}
}
{
  "code": "svix"
}

Retrieving a webhook config

get

Retrieves a webhook configuration for a given tenant.

Required scopes
This endpoint requires the following scopes:
  • : Needed to read subscriptions.
Authorizations
OAuth2clientCredentialsRequired
Token URL:
Path parameters
tenantstringRequired

Your Emporix tenant name.

Note: The tenant name should always be provided in lowercase.

codestringRequired

Unique identifier of the webhook configuration type.

Responses
200

Returning a webhook config.

application/json
activebooleanOptional

Indicates whether a given configuration is active. Only one configuration can be active at a time.

providerstring · enumOptional

Indicates which provider should be used.

Possible values:
codestringOptional

Unique identifier of the webhook configuration type.

configurationone ofOptional
get/webhook/{tenant}/config/{code}
GET /webhook/{tenant}/config/{code} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "code": "svix_shared",
  "provider": "SVIX_SHARED",
  "active": true
}

Updating a single webhook config

put

Updates a webhook config for a given tenant. Currently the service supports the following webhook providers:

  • Svix Emporix Shared Account

  • Svix Custom Account

  • HTTP Webhook Strategy

NOTE For HTTP configurations, eventsConfiguration can contain multiple entries for the same eventType. Existing entry id values must be preserved when updating known entries. Legacy payloads without entry ids are still accepted; the server assigns ids to id-less entries (and reuses an existing id when both the stored config and the payload have exactly one entry for that event type).

Required scopes
This endpoint requires the following scopes:
  • : Needed to manage subscriptions.
Authorizations
OAuth2clientCredentialsRequired
Token URL:
Path parameters
tenantstringRequired

Your Emporix tenant name.

Note: The tenant name should always be provided in lowercase.

codestringRequired

Unique identifier of the webhook configuration type.

Body
activebooleanOptional

Indicates whether a given configuration is active. Only one configuration can be active at a time.

providerstring · enumRequired

Indicates which provider should be used.

Possible values:
configurationone ofOptional
object · EmptyConfigurationOptional

SVIX_SHARED config

or
or
Responses
204

No content

No content
put/webhook/{tenant}/config/{code}
PUT /webhook/{tenant}/config/{code} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 59

{
  "active": true,
  "provider": "SVIX_SHARED",
  "configuration": {}
}
No content

Removing a webhook config

delete

Removes a webhook configuration for a given tenant.

Required scopes
This endpoint requires the following scopes:
  • : Needed to manage subscriptions.
Authorizations
OAuth2clientCredentialsRequired
Token URL:
Path parameters
tenantstringRequired

Your Emporix tenant name.

Note: The tenant name should always be provided in lowercase.

codestringRequired

Unique identifier of the webhook configuration type.

Query parameters
forcebooleanOptional

This flag set to "true" allows to delete active config

Default: false
Responses
204

No content

No content
delete/webhook/{tenant}/config/{code}
DELETE /webhook/{tenant}/config/{code} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

No content

Partially updating a webhook config

patch

Partially updates a webhook config for a given tenant. Single update may contain multiple partial updates in the form of an array. Following operations are allowed:

  • REMOVE - removing an item from the list

  • UPSERT - adding or updating given property

For HTTP eventsConfiguration:

  • Create a new entry with UPSERT on /configuration/http/eventsConfigurationEntry (no id segment). Do not send id in the body — the server generates it. REMOVE is not supported on this path.

  • Address an existing entry by id with /configuration/http/eventsConfigurationEntry/{entryId} (and field subpaths for destinationUrl, secretKey, headers, filter, excludedFields, name, and active).

  • Deactivate a single endpoint with UPSERT on /configuration/http/eventsConfigurationEntry/{entryId}/active and value false. Events for a deactivated endpoint are dropped without filter evaluation, delivery, or retries; other endpoints are not affected. Set the value back to true to resume deliveries.

  • Legacy /configuration/http/eventsConfiguration/{eventType} paths remain supported when at most one entry exists for that event type and return 409 Conflict when multiple entries exist.

  • Create/update requests return 400 Bad Request when the body supplies a client-minted entry id or the JsonPath filter is invalid.

Required scopes
This endpoint requires the following scopes:
  • : Needed to manage subscriptions.
Authorizations
OAuth2clientCredentialsRequired
Token URL:
Path parameters
tenantstringRequired

Your Emporix tenant name.

Note: The tenant name should always be provided in lowercase.

codestringRequired

Unique identifier of the webhook configuration type.

Bodyobject · WebhookConfigPartialUpdate[]
opstring · enumRequired

Kind of the update operation

Possible values:
pathstring · enumRequired

Path identifying which properties should be updated. Use UPSERT on /configuration/http/eventsConfigurationEntry (no id) to create a new entry — body must omit id (server-generated); REMOVE on this path is rejected. Prefer /configuration/http/eventsConfigurationEntry/{entryId} paths to address a specific existing entry. Use UPSERT on /configuration/http/eventsConfigurationEntry/{entryId}/active with a boolean value to deactivate (false) or reactivate (true) a single endpoint without removing it; the value is required. Legacy /configuration/http/eventsConfiguration/{eventType} paths remain supported when at most one entry exists for that event type; they return 409 when multiple entries exist. Create/update can return 400 for a client-supplied entry id or an invalid JsonPath filter.

Possible values:
valueany ofOptional
or
or
stringOptional

Svix Api Key

or
booleanOptional

Active flag (config-level on /active, per-endpoint on /configuration/http/eventsConfigurationEntry/{entryId}/active)

or
stringOptional

Destination URL where event should be sent

or
stringOptional

Secret key needed to sign messages sent via HTTP requests.

or
stringOptional

JsonPath filter expression

or
string[]Optional

Per-entry excluded fields

or
or
Responses
204

No content

No content
patch/webhook/{tenant}/config/{code}
PATCH /webhook/{tenant}/config/{code} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 131

[
  {
    "op": "UPSERT",
    "path": "/active",
    "value": true
  },
  {
    "op": "UPSERT",
    "path": "/configuration/svix/apiKey",
    "value": "SARFJ353DSTGSd3w3cZXX"
  }
]
No content
PreviousAPI Reference
NextEvents

Last updated

Was this helpful?