> For the complete documentation index, see [llms.txt](https://developer.emporix.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.emporix.io/api-references-1/readme/api-reference-42/config.md).
# Config
## Retrieving a list of webhook configs
> 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\`.
```json
{"openapi":"3.0.0","info":{"title":"Webhook Service","version":"0.0.1"},"tags":[{"name":"Config"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["webhook.subscription_read"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"scopes":{"webhook.subscription_read":"Needed to read subscriptions.","webhook.subscription_manage":"Needed to manage subscriptions."},"tokenUrl":"https://api.emporix.io/oauth/token"}}}},"responses":{"WebhookConfigsResponse":{"description":"Returning list of webhook configs.","content":{"application/json":{"schema":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/AbstractWebhookConfig"},{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ConfigCode"},"configuration":{"$ref":"#/components/schemas/ConfigurationGet"}}}]}}}}},"Unauthorized_401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Forbidden_403":{"description":"Given authorization scopes are not sufficient and do not match the scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"InternalServerError_500":{"description":"Some server-side error occurred. Details are provided in the response payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}},"schemas":{"AbstractWebhookConfig":{"type":"object","properties":{"active":{"type":"boolean","description":"Indicates whether a given configuration is active. Only one configuration can be active at a time."},"provider":{"$ref":"#/components/schemas/Provider","description":"Indicates which provider should be used."}}},"Provider":{"type":"string","enum":["SVIX_SHARED","SVIX","HTTP"],"description":"Webhook provider strategy. Maps to configuration types as follows:\n\n* `SVIX` – `svix`\n* `SVIX_SHARED` – `svix_shared`\n* `HTTP` – `http`"},"ConfigCode":{"type":"string","description":"Unique identifier of the webhook configuration type."},"ConfigurationGet":{"oneOf":[{"type":"object","properties":{"destinationUrl":{"type":"string","description":"Destination URL where event should be sent."},"secretKeyExists":{"type":"boolean","description":"Information if secret key for securing the messages has been provided."},"headers":{"allOf":[{"$ref":"#/components/schemas/HttpHeadersConfig"}],"description":"List of key-value pairs which can decorate outgoing HTTP POST request as headers."},"eventsConfiguration":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable server-generated identifier of this event configuration entry."},"eventType":{"type":"string","description":"Type of the event. Multiple entries may share the same `eventType`."},"destinationUrl":{"type":"string","description":"Destination URL where event should be sent."},"secretKeyExists":{"type":"boolean","description":"Information if secret key for securing the messages has been provided."},"headers":{"allOf":[{"$ref":"#/components/schemas/HttpHeadersConfig"}],"description":"List of key-value pairs which can decorate outgoing HTTP POST request as headers."},"filter":{"type":"string","description":"Optional Jayway JsonPath predicate. When omitted, the entry matches every event of the given `eventType`."},"excludedFields":{"type":"array","items":{"type":"string"},"description":"Per-entry field exclusion list. Omitted or `null` means inherit the event-subscription exclusions. An empty array `[]` overrides with no exclusions for this target."},"active":{"type":"boolean","description":"Per-endpoint activation switch. Always returned as an explicit boolean; entries created before the flag existed report `true`. When `false`, events for this endpoint are dropped without filter evaluation, delivery, or retries."}}}}}}]},"HttpHeadersConfig":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/HttpHeaderConfigValue"}},"HttpHeaderConfigValue":{"type":"object","properties":{"value":{"type":"string"}}},"ErrorMessage":{"title":"Error message","description":"Object returned in error responses.","type":"object","properties":{"code":{"description":"Original HTTP error code. Must be consistent with the response HTTP code.","type":"integer"},"status":{"type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"},"details":{"description":"List of problems causing the error.","type":"array","items":{"type":"string"}}},"required":["code","status"]}}},"paths":{"/webhook/{tenant}/config":{"get":{"summary":"Retrieving a list of webhook configs","operationId":"GET-webhook-list-configs","responses":{"200":{"$ref":"#/components/responses/WebhookConfigsResponse"},"401":{"$ref":"#/components/responses/Unauthorized_401"},"403":{"$ref":"#/components/responses/Forbidden_403"},"500":{"$ref":"#/components/responses/InternalServerError_500"}},"tags":["Config"],"description":"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`.\n"}}}}
```
## Creating a single webhook config
> 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.
```json
{"openapi":"3.0.0","info":{"title":"Webhook Service","version":"0.0.1"},"tags":[{"name":"Config"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["webhook.subscription_manage"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"scopes":{"webhook.subscription_read":"Needed to read subscriptions.","webhook.subscription_manage":"Needed to manage subscriptions."},"tokenUrl":"https://api.emporix.io/oauth/token"}}}},"responses":{"CreateConfigResponse":{"description":"Result of creating config","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"}}}}}},"BadRequest_400":{"description":"Request was syntactically incorrect. Details are provided in the response payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"Unauthorized_401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Forbidden_403":{"description":"Given authorization scopes are not sufficient and do not match the scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"Conflict_409":{"description":"Conflict. Returned when creating a webhook configuration for a type that is already configured, or when a legacy event-type PATCH path is used while multiple `eventsConfiguration` entries exist for that event type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"InternalServerError_500":{"description":"Some server-side error occurred. Details are provided in the response payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}},"schemas":{"ErrorMessage":{"title":"Error message","description":"Object returned in error responses.","type":"object","properties":{"code":{"description":"Original HTTP error code. Must be consistent with the response HTTP code.","type":"integer"},"status":{"type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"},"details":{"description":"List of problems causing the error.","type":"array","items":{"type":"string"}}},"required":["code","status"]},"WebhookConfigCreation":{"allOf":[{"$ref":"#/components/schemas/WebhookConfigUpdate"},{"type":"object","required":["code"],"properties":{"code":{"allOf":[{"$ref":"#/components/schemas/ConfigCode"}]}}}]},"WebhookConfigUpdate":{"allOf":[{"$ref":"#/components/schemas/AbstractWebhookConfig"},{"type":"object","required":["provider"],"properties":{"configuration":{"$ref":"#/components/schemas/Configuration"}}}]},"AbstractWebhookConfig":{"type":"object","properties":{"active":{"type":"boolean","description":"Indicates whether a given configuration is active. Only one configuration can be active at a time."},"provider":{"$ref":"#/components/schemas/Provider","description":"Indicates which provider should be used."}}},"Provider":{"type":"string","enum":["SVIX_SHARED","SVIX","HTTP"],"description":"Webhook provider strategy. Maps to configuration types as follows:\n\n* `SVIX` – `svix`\n* `SVIX_SHARED` – `svix_shared`\n* `HTTP` – `http`"},"Configuration":{"type":"object","oneOf":[{"$ref":"#/components/schemas/EmptyConfiguration"},{"$ref":"#/components/schemas/SvixConfig"},{"$ref":"#/components/schemas/HttpConfig"}]},"EmptyConfiguration":{"type":"object","description":"SVIX_SHARED config"},"SvixConfig":{"type":"object","properties":{"apiKey":{"type":"string","description":"API Key for connecting to SVIX. This API Key will be then used in `Authorization` header while sending requests to SVIX, so the value should include `Bearer` prefix if necessary."}},"description":"SVIX config"},"HttpConfig":{"type":"object","properties":{"secretKey":{"type":"string","description":"Optional secret key which could be used to sign the message. This secret is used in `HMAC SHA 256` algorithm which encrypts the payload. Then this value is encoded to `BASE256` and included in `emporix-event-signature` header of HTTP request."},"destinationUrl":{"type":"string","description":"Destination URL where event should be sent."},"headers":{"allOf":[{"$ref":"#/components/schemas/HttpHeadersConfig"}],"description":"List of key-value pairs which can decorate outgoing HTTP POST request as headers. The size limit for this list is `10`."},"eventsConfiguration":{"$ref":"#/components/schemas/EventsConfiguration"}},"description":"HTTP config"},"HttpHeadersConfig":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/HttpHeaderConfigValue"}},"HttpHeaderConfigValue":{"type":"object","properties":{"value":{"type":"string"}}},"EventsConfiguration":{"type":"array","description":"List of HTTP event-specific configuration entries. Multiple entries for the same `eventType` are allowed. Uniqueness is by entry `id`. Duplicate entry ids are rejected with `400`.","items":{"$ref":"#/components/schemas/EventConfiguration"}},"EventConfiguration":{"type":"object","properties":{"id":{"type":"string","description":"Stable server-generated identifier of this event configuration entry. Omit on create; client-supplied ids are rejected with `400`. On update, known ids must refer to existing entries; unknown ids are rejected with `400`. Ids are immutable once assigned."},"name":{"type":"string","maxLength":255,"description":"Optional user-facing label for this entry (for example \"ERP integration\"). Purely descriptive — it has no impact on delivery. Maximum 255 characters."},"eventType":{"type":"string","description":"Unique identifier of the event. Multiple entries may share the same `eventType`."},"secretKey":{"type":"string","description":"Optional secret key which could be used to sign the message. This secret is used in `HMAC SHA 256` algorithm which encrypts the payload. Then this value is encoded to `BASE256` and included in `emporix-event-signature` header of HTTP request. It has higher priority than `secretKey` on root level. Each event can have defined a separated secret key."},"destinationUrl":{"type":"string","description":"Destination URL where event should be sent. It has higher priority than `destinationUrl` on root level. Each event can have defined a separated destination url."},"headers":{"allOf":[{"$ref":"#/components/schemas/HttpHeadersConfig"}],"description":"List of key-value pairs which can decorate outgoing HTTP POST request as headers. The size limit for this list is `10`. It has higher priority than `headers` on root level. Each event can have defined a separated headers."},"filter":{"type":"string","description":"Optional Jayway JsonPath predicate evaluated against the event payload. When omitted or empty, the entry matches every event of the given `eventType`. Invalid expressions are rejected with `400`. Examples: `$[?(@.status == 'DECLINED')]`, `$[?(@.total.amount > 100)]`."},"excludedFields":{"type":"array","items":{"type":"string"},"description":"Optional per-entry field exclusion list. Only non-blank top-level field names are allowed. Omit or set to `null` to inherit the event-subscription `excludedFields`. An empty array `[]` overrides the subscription exclusions with no exclusions for this target."},"active":{"type":"boolean","default":true,"description":"Per-endpoint activation switch. When `false`, events for this endpoint are dropped without filter evaluation, delivery, or retries; other endpoints are not affected. Omitted means active."}}},"ConfigCode":{"type":"string","description":"Unique identifier of the webhook configuration type."}}},"paths":{"/webhook/{tenant}/config":{"post":{"summary":"Creating a single webhook config","responses":{"201":{"$ref":"#/components/responses/CreateConfigResponse"},"400":{"$ref":"#/components/responses/BadRequest_400"},"401":{"$ref":"#/components/responses/Unauthorized_401"},"403":{"$ref":"#/components/responses/Forbidden_403"},"409":{"$ref":"#/components/responses/Conflict_409"},"500":{"$ref":"#/components/responses/InternalServerError_500"}},"description":"Creates a new webhook config for a given tenant. Currently the service supports the following webhook providers:\n\n* Svix Emporix Shared Account\n* Svix Custom Account\n* HTTP Webhook Strategy \n\n**NOTE**\nAt 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.\n\n**NOTE**\nFor 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`.\n\n**NOTE**\nSvix 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.\n","operationId":"POST-webhook-create-config","tags":["Config"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookConfigCreation"}}},"description":""}}}}}
```
## Retrieving a webhook config
> Retrieves a webhook configuration for a given tenant.
```json
{"openapi":"3.0.0","info":{"title":"Webhook Service","version":"0.0.1"},"tags":[{"name":"Config"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["webhook.subscription_read"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"scopes":{"webhook.subscription_read":"Needed to read subscriptions.","webhook.subscription_manage":"Needed to manage subscriptions."},"tokenUrl":"https://api.emporix.io/oauth/token"}}}},"responses":{"WebhookConfigResponse":{"description":"Returning a webhook config.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/AbstractWebhookConfig"},{"type":"object","properties":{"code":{"$ref":"#/components/schemas/ConfigCode"},"configuration":{"$ref":"#/components/schemas/ConfigurationGet"}}}]}}}},"Unauthorized_401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Forbidden_403":{"description":"Given authorization scopes are not sufficient and do not match the scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"NotFound_404":{"description":"The requested resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"InternalServerError_500":{"description":"Some server-side error occurred. Details are provided in the response payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}},"schemas":{"AbstractWebhookConfig":{"type":"object","properties":{"active":{"type":"boolean","description":"Indicates whether a given configuration is active. Only one configuration can be active at a time."},"provider":{"$ref":"#/components/schemas/Provider","description":"Indicates which provider should be used."}}},"Provider":{"type":"string","enum":["SVIX_SHARED","SVIX","HTTP"],"description":"Webhook provider strategy. Maps to configuration types as follows:\n\n* `SVIX` – `svix`\n* `SVIX_SHARED` – `svix_shared`\n* `HTTP` – `http`"},"ConfigCode":{"type":"string","description":"Unique identifier of the webhook configuration type."},"ConfigurationGet":{"oneOf":[{"type":"object","properties":{"destinationUrl":{"type":"string","description":"Destination URL where event should be sent."},"secretKeyExists":{"type":"boolean","description":"Information if secret key for securing the messages has been provided."},"headers":{"allOf":[{"$ref":"#/components/schemas/HttpHeadersConfig"}],"description":"List of key-value pairs which can decorate outgoing HTTP POST request as headers."},"eventsConfiguration":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Stable server-generated identifier of this event configuration entry."},"eventType":{"type":"string","description":"Type of the event. Multiple entries may share the same `eventType`."},"destinationUrl":{"type":"string","description":"Destination URL where event should be sent."},"secretKeyExists":{"type":"boolean","description":"Information if secret key for securing the messages has been provided."},"headers":{"allOf":[{"$ref":"#/components/schemas/HttpHeadersConfig"}],"description":"List of key-value pairs which can decorate outgoing HTTP POST request as headers."},"filter":{"type":"string","description":"Optional Jayway JsonPath predicate. When omitted, the entry matches every event of the given `eventType`."},"excludedFields":{"type":"array","items":{"type":"string"},"description":"Per-entry field exclusion list. Omitted or `null` means inherit the event-subscription exclusions. An empty array `[]` overrides with no exclusions for this target."},"active":{"type":"boolean","description":"Per-endpoint activation switch. Always returned as an explicit boolean; entries created before the flag existed report `true`. When `false`, events for this endpoint are dropped without filter evaluation, delivery, or retries."}}}}}}]},"HttpHeadersConfig":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/HttpHeaderConfigValue"}},"HttpHeaderConfigValue":{"type":"object","properties":{"value":{"type":"string"}}},"ErrorMessage":{"title":"Error message","description":"Object returned in error responses.","type":"object","properties":{"code":{"description":"Original HTTP error code. Must be consistent with the response HTTP code.","type":"integer"},"status":{"type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"},"details":{"description":"List of problems causing the error.","type":"array","items":{"type":"string"}}},"required":["code","status"]}}},"paths":{"/webhook/{tenant}/config/{code}":{"get":{"summary":"Retrieving a webhook config","operationId":"GET-webhook-retrieve-config","responses":{"200":{"$ref":"#/components/responses/WebhookConfigResponse"},"401":{"$ref":"#/components/responses/Unauthorized_401"},"403":{"$ref":"#/components/responses/Forbidden_403"},"404":{"$ref":"#/components/responses/NotFound_404"},"500":{"$ref":"#/components/responses/InternalServerError_500"}},"tags":["Config"],"description":"Retrieves a webhook configuration for a given tenant. \n"}}}}
```
## Updating a single webhook config
> 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).
```json
{"openapi":"3.0.0","info":{"title":"Webhook Service","version":"0.0.1"},"tags":[{"name":"Config"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["webhook.subscription_manage"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"scopes":{"webhook.subscription_read":"Needed to read subscriptions.","webhook.subscription_manage":"Needed to manage subscriptions."},"tokenUrl":"https://api.emporix.io/oauth/token"}}}},"responses":{"BadRequest_400":{"description":"Request was syntactically incorrect. Details are provided in the response payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"Unauthorized_401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Forbidden_403":{"description":"Given authorization scopes are not sufficient and do not match the scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"Conflict_409":{"description":"Conflict. Returned when creating a webhook configuration for a type that is already configured, or when a legacy event-type PATCH path is used while multiple `eventsConfiguration` entries exist for that event type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"InternalServerError_500":{"description":"Some server-side error occurred. Details are provided in the response payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}},"schemas":{"ErrorMessage":{"title":"Error message","description":"Object returned in error responses.","type":"object","properties":{"code":{"description":"Original HTTP error code. Must be consistent with the response HTTP code.","type":"integer"},"status":{"type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"},"details":{"description":"List of problems causing the error.","type":"array","items":{"type":"string"}}},"required":["code","status"]},"WebhookConfigUpdate":{"allOf":[{"$ref":"#/components/schemas/AbstractWebhookConfig"},{"type":"object","required":["provider"],"properties":{"configuration":{"$ref":"#/components/schemas/Configuration"}}}]},"AbstractWebhookConfig":{"type":"object","properties":{"active":{"type":"boolean","description":"Indicates whether a given configuration is active. Only one configuration can be active at a time."},"provider":{"$ref":"#/components/schemas/Provider","description":"Indicates which provider should be used."}}},"Provider":{"type":"string","enum":["SVIX_SHARED","SVIX","HTTP"],"description":"Webhook provider strategy. Maps to configuration types as follows:\n\n* `SVIX` – `svix`\n* `SVIX_SHARED` – `svix_shared`\n* `HTTP` – `http`"},"Configuration":{"type":"object","oneOf":[{"$ref":"#/components/schemas/EmptyConfiguration"},{"$ref":"#/components/schemas/SvixConfig"},{"$ref":"#/components/schemas/HttpConfig"}]},"EmptyConfiguration":{"type":"object","description":"SVIX_SHARED config"},"SvixConfig":{"type":"object","properties":{"apiKey":{"type":"string","description":"API Key for connecting to SVIX. This API Key will be then used in `Authorization` header while sending requests to SVIX, so the value should include `Bearer` prefix if necessary."}},"description":"SVIX config"},"HttpConfig":{"type":"object","properties":{"secretKey":{"type":"string","description":"Optional secret key which could be used to sign the message. This secret is used in `HMAC SHA 256` algorithm which encrypts the payload. Then this value is encoded to `BASE256` and included in `emporix-event-signature` header of HTTP request."},"destinationUrl":{"type":"string","description":"Destination URL where event should be sent."},"headers":{"allOf":[{"$ref":"#/components/schemas/HttpHeadersConfig"}],"description":"List of key-value pairs which can decorate outgoing HTTP POST request as headers. The size limit for this list is `10`."},"eventsConfiguration":{"$ref":"#/components/schemas/EventsConfiguration"}},"description":"HTTP config"},"HttpHeadersConfig":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/HttpHeaderConfigValue"}},"HttpHeaderConfigValue":{"type":"object","properties":{"value":{"type":"string"}}},"EventsConfiguration":{"type":"array","description":"List of HTTP event-specific configuration entries. Multiple entries for the same `eventType` are allowed. Uniqueness is by entry `id`. Duplicate entry ids are rejected with `400`.","items":{"$ref":"#/components/schemas/EventConfiguration"}},"EventConfiguration":{"type":"object","properties":{"id":{"type":"string","description":"Stable server-generated identifier of this event configuration entry. Omit on create; client-supplied ids are rejected with `400`. On update, known ids must refer to existing entries; unknown ids are rejected with `400`. Ids are immutable once assigned."},"name":{"type":"string","maxLength":255,"description":"Optional user-facing label for this entry (for example \"ERP integration\"). Purely descriptive — it has no impact on delivery. Maximum 255 characters."},"eventType":{"type":"string","description":"Unique identifier of the event. Multiple entries may share the same `eventType`."},"secretKey":{"type":"string","description":"Optional secret key which could be used to sign the message. This secret is used in `HMAC SHA 256` algorithm which encrypts the payload. Then this value is encoded to `BASE256` and included in `emporix-event-signature` header of HTTP request. It has higher priority than `secretKey` on root level. Each event can have defined a separated secret key."},"destinationUrl":{"type":"string","description":"Destination URL where event should be sent. It has higher priority than `destinationUrl` on root level. Each event can have defined a separated destination url."},"headers":{"allOf":[{"$ref":"#/components/schemas/HttpHeadersConfig"}],"description":"List of key-value pairs which can decorate outgoing HTTP POST request as headers. The size limit for this list is `10`. It has higher priority than `headers` on root level. Each event can have defined a separated headers."},"filter":{"type":"string","description":"Optional Jayway JsonPath predicate evaluated against the event payload. When omitted or empty, the entry matches every event of the given `eventType`. Invalid expressions are rejected with `400`. Examples: `$[?(@.status == 'DECLINED')]`, `$[?(@.total.amount > 100)]`."},"excludedFields":{"type":"array","items":{"type":"string"},"description":"Optional per-entry field exclusion list. Only non-blank top-level field names are allowed. Omit or set to `null` to inherit the event-subscription `excludedFields`. An empty array `[]` overrides the subscription exclusions with no exclusions for this target."},"active":{"type":"boolean","default":true,"description":"Per-endpoint activation switch. When `false`, events for this endpoint are dropped without filter evaluation, delivery, or retries; other endpoints are not affected. Omitted means active."}}}}},"paths":{"/webhook/{tenant}/config/{code}":{"put":{"summary":"Updating a single webhook config","responses":{"204":{"description":"No content"},"400":{"$ref":"#/components/responses/BadRequest_400"},"401":{"$ref":"#/components/responses/Unauthorized_401"},"403":{"$ref":"#/components/responses/Forbidden_403"},"409":{"$ref":"#/components/responses/Conflict_409"},"500":{"$ref":"#/components/responses/InternalServerError_500"}},"description":"Updates a webhook config for a given tenant. Currently the service supports the following webhook providers:\n\n* Svix Emporix Shared Account\n* Svix Custom Account\n* HTTP Webhook Strategy\n\n**NOTE**\nFor 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).\n","operationId":"PUT-webhook-update-config","tags":["Config"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookConfigUpdate"}}},"description":""}}}}}
```
## Removing a webhook config
> Removes a webhook configuration for a given tenant.
```json
{"openapi":"3.0.0","info":{"title":"Webhook Service","version":"0.0.1"},"tags":[{"name":"Config"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["webhook.subscription_manage"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"scopes":{"webhook.subscription_read":"Needed to read subscriptions.","webhook.subscription_manage":"Needed to manage subscriptions."},"tokenUrl":"https://api.emporix.io/oauth/token"}}}},"responses":{"Unauthorized_401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Forbidden_403":{"description":"Given authorization scopes are not sufficient and do not match the scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"InternalServerError_500":{"description":"Some server-side error occurred. Details are provided in the response payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}},"schemas":{"ErrorMessage":{"title":"Error message","description":"Object returned in error responses.","type":"object","properties":{"code":{"description":"Original HTTP error code. Must be consistent with the response HTTP code.","type":"integer"},"status":{"type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"},"details":{"description":"List of problems causing the error.","type":"array","items":{"type":"string"}}},"required":["code","status"]}}},"paths":{"/webhook/{tenant}/config/{code}":{"delete":{"parameters":[{"name":"force","in":"query","required":false,"schema":{"type":"boolean","default":false},"description":"This flag set to \"true\" allows to delete active config"}],"summary":"Removing a webhook config","operationId":"DELETE-webhook-remove-config","responses":{"204":{"description":"No content"},"401":{"$ref":"#/components/responses/Unauthorized_401"},"403":{"$ref":"#/components/responses/Forbidden_403"},"500":{"$ref":"#/components/responses/InternalServerError_500"}},"tags":["Config"],"description":"Removes a webhook configuration for a given tenant. \n"}}}}
```
## Partially updating a webhook config
> 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.
```json
{"openapi":"3.0.0","info":{"title":"Webhook Service","version":"0.0.1"},"tags":[{"name":"Config"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["webhook.subscription_manage"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"scopes":{"webhook.subscription_read":"Needed to read subscriptions.","webhook.subscription_manage":"Needed to manage subscriptions."},"tokenUrl":"https://api.emporix.io/oauth/token"}}}},"responses":{"BadRequest_400":{"description":"Request was syntactically incorrect. Details are provided in the response payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"Unauthorized_401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Forbidden_403":{"description":"Given authorization scopes are not sufficient and do not match the scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"Conflict_409":{"description":"Conflict. Returned when creating a webhook configuration for a type that is already configured, or when a legacy event-type PATCH path is used while multiple `eventsConfiguration` entries exist for that event type.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"InternalServerError_500":{"description":"Some server-side error occurred. Details are provided in the response payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}},"schemas":{"ErrorMessage":{"title":"Error message","description":"Object returned in error responses.","type":"object","properties":{"code":{"description":"Original HTTP error code. Must be consistent with the response HTTP code.","type":"integer"},"status":{"type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"},"details":{"description":"List of problems causing the error.","type":"array","items":{"type":"string"}}},"required":["code","status"]},"WebhookConfigPartialUpdates":{"type":"array","items":{"$ref":"#/components/schemas/WebhookConfigPartialUpdate"}},"WebhookConfigPartialUpdate":{"type":"object","properties":{"op":{"type":"string","enum":["REMOVE","UPSERT"],"description":"Kind of the update operation"},"path":{"type":"string","enum":["/active","/configuration","/configuration/svix/apiKey","/configuration/http/headers","/configuration/http/destinationUrl","/configuration/http/secretKey","/configuration/http/eventsConfiguration","/configuration/http/eventsConfiguration/{eventType}","/configuration/http/eventsConfiguration/{eventType}/destinationUrl","/configuration/http/eventsConfiguration/{eventType}/secretKey","/configuration/http/eventsConfiguration/{eventType}/headers","/configuration/http/eventsConfigurationEntry","/configuration/http/eventsConfigurationEntry/{entryId}","/configuration/http/eventsConfigurationEntry/{entryId}/destinationUrl","/configuration/http/eventsConfigurationEntry/{entryId}/secretKey","/configuration/http/eventsConfigurationEntry/{entryId}/headers","/configuration/http/eventsConfigurationEntry/{entryId}/filter","/configuration/http/eventsConfigurationEntry/{entryId}/excludedFields","/configuration/http/eventsConfigurationEntry/{entryId}/name","/configuration/http/eventsConfigurationEntry/{entryId}/active"],"description":"Path identifying which properties should be updated.\nUse `UPSERT` on `/configuration/http/eventsConfigurationEntry` (no id) to create a new entry — body must omit `id` (server-generated); `REMOVE` on this path is rejected.\nPrefer `/configuration/http/eventsConfigurationEntry/{entryId}` paths to address a specific existing entry.\nUse `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.\nLegacy `/configuration/http/eventsConfiguration/{eventType}` paths remain supported when at most one entry exists for that event type; they return `409` when multiple entries exist.\nCreate/update can return `400` for a client-supplied entry id or an invalid JsonPath `filter`."},"value":{"type":"object","anyOf":[{"$ref":"#/components/schemas/SvixConfig"},{"$ref":"#/components/schemas/HttpConfig"},{"type":"string","description":"Svix Api Key"},{"type":"boolean","description":"Active flag (config-level on `/active`, per-endpoint on `/configuration/http/eventsConfigurationEntry/{entryId}/active`)"},{"type":"string","description":"Destination URL where event should be sent"},{"type":"string","description":"Secret key needed to sign messages sent via HTTP requests."},{"type":"string","description":"JsonPath filter expression"},{"type":"array","items":{"type":"string"},"description":"Per-entry excluded fields"},{"$ref":"#/components/schemas/EventsConfiguration"},{"$ref":"#/components/schemas/EventConfiguration"}]}},"required":["op","path"]},"SvixConfig":{"type":"object","properties":{"apiKey":{"type":"string","description":"API Key for connecting to SVIX. This API Key will be then used in `Authorization` header while sending requests to SVIX, so the value should include `Bearer` prefix if necessary."}},"description":"SVIX config"},"HttpConfig":{"type":"object","properties":{"secretKey":{"type":"string","description":"Optional secret key which could be used to sign the message. This secret is used in `HMAC SHA 256` algorithm which encrypts the payload. Then this value is encoded to `BASE256` and included in `emporix-event-signature` header of HTTP request."},"destinationUrl":{"type":"string","description":"Destination URL where event should be sent."},"headers":{"allOf":[{"$ref":"#/components/schemas/HttpHeadersConfig"}],"description":"List of key-value pairs which can decorate outgoing HTTP POST request as headers. The size limit for this list is `10`."},"eventsConfiguration":{"$ref":"#/components/schemas/EventsConfiguration"}},"description":"HTTP config"},"HttpHeadersConfig":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/HttpHeaderConfigValue"}},"HttpHeaderConfigValue":{"type":"object","properties":{"value":{"type":"string"}}},"EventsConfiguration":{"type":"array","description":"List of HTTP event-specific configuration entries. Multiple entries for the same `eventType` are allowed. Uniqueness is by entry `id`. Duplicate entry ids are rejected with `400`.","items":{"$ref":"#/components/schemas/EventConfiguration"}},"EventConfiguration":{"type":"object","properties":{"id":{"type":"string","description":"Stable server-generated identifier of this event configuration entry. Omit on create; client-supplied ids are rejected with `400`. On update, known ids must refer to existing entries; unknown ids are rejected with `400`. Ids are immutable once assigned."},"name":{"type":"string","maxLength":255,"description":"Optional user-facing label for this entry (for example \"ERP integration\"). Purely descriptive — it has no impact on delivery. Maximum 255 characters."},"eventType":{"type":"string","description":"Unique identifier of the event. Multiple entries may share the same `eventType`."},"secretKey":{"type":"string","description":"Optional secret key which could be used to sign the message. This secret is used in `HMAC SHA 256` algorithm which encrypts the payload. Then this value is encoded to `BASE256` and included in `emporix-event-signature` header of HTTP request. It has higher priority than `secretKey` on root level. Each event can have defined a separated secret key."},"destinationUrl":{"type":"string","description":"Destination URL where event should be sent. It has higher priority than `destinationUrl` on root level. Each event can have defined a separated destination url."},"headers":{"allOf":[{"$ref":"#/components/schemas/HttpHeadersConfig"}],"description":"List of key-value pairs which can decorate outgoing HTTP POST request as headers. The size limit for this list is `10`. It has higher priority than `headers` on root level. Each event can have defined a separated headers."},"filter":{"type":"string","description":"Optional Jayway JsonPath predicate evaluated against the event payload. When omitted or empty, the entry matches every event of the given `eventType`. Invalid expressions are rejected with `400`. Examples: `$[?(@.status == 'DECLINED')]`, `$[?(@.total.amount > 100)]`."},"excludedFields":{"type":"array","items":{"type":"string"},"description":"Optional per-entry field exclusion list. Only non-blank top-level field names are allowed. Omit or set to `null` to inherit the event-subscription `excludedFields`. An empty array `[]` overrides the subscription exclusions with no exclusions for this target."},"active":{"type":"boolean","default":true,"description":"Per-endpoint activation switch. When `false`, events for this endpoint are dropped without filter evaluation, delivery, or retries; other endpoints are not affected. Omitted means active."}}}}},"paths":{"/webhook/{tenant}/config/{code}":{"patch":{"summary":"Partially updating a webhook config","operationId":"PATCH-webhook-update-config","responses":{"204":{"description":"No content"},"400":{"$ref":"#/components/responses/BadRequest_400"},"401":{"$ref":"#/components/responses/Unauthorized_401"},"403":{"$ref":"#/components/responses/Forbidden_403"},"409":{"$ref":"#/components/responses/Conflict_409"},"500":{"$ref":"#/components/responses/InternalServerError_500"}},"description":"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:\n* `REMOVE` - removing an item from the list\n* `UPSERT` - adding or updating given property\n\nFor HTTP `eventsConfiguration`:\n* 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.\n* Address an existing entry by id with `/configuration/http/eventsConfigurationEntry/{entryId}` (and field subpaths for `destinationUrl`, `secretKey`, `headers`, `filter`, `excludedFields`, `name`, and `active`).\n* 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.\n* 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.\n* Create/update requests return `400 Bad Request` when the body supplies a client-minted entry id or the JsonPath `filter` is invalid.\n","tags":["Config"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookConfigPartialUpdates"}}},"description":""}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://developer.emporix.io/api-references-1/readme/api-reference-42/config.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.