Webhook Service

Download OpenAPI specification:Download

Manage the webhook configuration to allow users to choose which events they want to receive via the Svix webhook provider.

Key Features:

View catalog
View configuration
Update configuration

Key Benefits:

View events catalog to be able to pick those that are of interest
Subscribe and unsubscribe from events without having to provide the full configuration
View current configuration

Config

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 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

webhook.subscription_manage

SecurityOAuth2

Request

path Parameters

tenant

required

string

Your Emporix tenant's name.

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

Request Body schema: application/json

code required	string Unique identifier of webhook configuration
	EmptyConfiguration (object) or SvixConfig (object) or HttpConfig (object) (Configuration)
active	boolean Indicates whether a given configuration is active. Only one configuration can be active.
provider required	string Indicates which provider should be used. Enum: "SVIX_SHARED" "SVIX" "HTTP"

Responses

201

Result of creating config

400

Request was syntactically incorrect. Details are provided in the response payload.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match the scopes required by the endpoint.

409

Conflict. The resource already exists.

500

Some server-side error occurred. Details are provided in the response payload.

post/{tenant}/config

Request samples

application/json

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

Response samples

application/json

{"code": "svix"
}

Retrieving a list of webhook configs

Retrieves a list of webhook configurations for a given tenant.

Required scopes

webhook.subscription_read

SecurityOAuth2

Request

path Parameters

tenant

required

string

Your Emporix tenant's name.

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

Responses

200

Returning list of webhook configs.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match the scopes required by the endpoint.

500

Some server-side error occurred. Details are provided in the response payload.

get/{tenant}/config

Request samples

Response samples

200
401
403
500

application/json

[{"code": "svix",
"provider": "SVIX_SHARED",
"active": true
}
]

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

Required scopes

webhook.subscription_manage

SecurityOAuth2

Request

path Parameters

tenant required	string Your Emporix tenant's name. Note: The tenant name should always be provided in lowercase.
code required	string Unique identifier of webhook config.

Request Body schema: application/json

	EmptyConfiguration (object) or SvixConfig (object) or HttpConfig (object) (Configuration)
active	boolean Indicates whether a given configuration is active. Only one configuration can be active.
provider required	string Indicates which provider should be used. Enum: "SVIX_SHARED" "SVIX" "HTTP"

Responses

204

No content

400

Request was syntactically incorrect. Details are provided in the response payload.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match the scopes required by the endpoint.

409

Conflict. The resource already exists.

500

Some server-side error occurred. Details are provided in the response payload.

put/{tenant}/config/{code}

Request samples

application/json

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

Response samples

400
401
403
409
500

application/json

{"code": 400,
"status": "Bad Request",
"message": "Tenant in the header is not matching with the one provided in the URI."
}

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

Required scopes

webhook.subscription_manage

SecurityOAuth2

Request

path Parameters

tenant required	string Your Emporix tenant's name. Note: The tenant name should always be provided in lowercase.
code required	string Unique identifier of webhook config.

Request Body schema: application/json

Array

op required	string Kind of the update operation Enum: "REMOVE" "UPSERT"
path required	string Path for identyifing which properties should be updated 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"
	SvixConfig (object) or HttpConfig (object) or object or object or object or object or EventsConfiguration (object) or EventConfiguration (object)

Responses

204

No content

400

Request was syntactically incorrect. Details are provided in the response payload.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match the scopes required by the endpoint.

500

Some server-side error occurred. Details are provided in the response payload.

patch/{tenant}/config/{code}

Request samples

application/json

[{"op": "UPSERT",
"path": "/active",
"value": true
},
{"op": "UPSERT",
"path": "/configuration/svix/apiKey",
"value": "SARFJ353DSTGSd3w3cZXX"
}
]

Response samples

400
401
403
500

application/json

{"code": 400,
"status": "Bad Request",
"message": "Tenant in the header is not matching with the one provided in the URI."
}

Retrieving a webhook config

Retrieves a webhook configuration for a given tenant.

Required scopes

webhook.subscription_read

SecurityOAuth2

Request

path Parameters

tenant required	string Your Emporix tenant's name. Note: The tenant name should always be provided in lowercase.
code required	string Unique identifier of webhook config.

Responses

200

Returning a webhook config.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match the scopes required by the endpoint.

404

The requested resource does not exist.

500

Some server-side error occurred. Details are provided in the response payload.

get/{tenant}/config/{code}

Request samples

Response samples

200
401
403
404
500

application/json

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

Removing a webhook config

Removes a webhook configuration for a given tenant.

Required scopes

webhook.subscription_manage

SecurityOAuth2

Request

path Parameters

tenant required	string Your Emporix tenant's name. Note: The tenant name should always be provided in lowercase.
code required	string Unique identifier of webhook config.

query Parameters

force

boolean

Default: false

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

Responses

204

No content

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match the scopes required by the endpoint.

500

Some server-side error occurred. Details are provided in the response payload.

delete/{tenant}/config/{code}

Request samples

Response samples

401
403
500

application/json

{"fault": {"faultstring": "Invalid access token",
"detail": {"errorcode": "oauth.v2.InvalidAccessToken"
}
}
}

Events

Subscribing and unsubscribing from events

Updates the list of subscriptions by either subscribing to or unsubscribing from specified events.

To receive events with fewer fields, you can specify the names of fields that you want to exclude in the 'fieldsToUnsubscribe' array. To re-include the previously excluded fields, you can provide their names in the 'fieldsToSubscribe' array.

Required scopes

webhook.subscription_manage

SecurityOAuth2

Request

path Parameters

tenant

required

string

Your Emporix tenant's name. Note: The tenant should always be written in lowercase.

Request Body schema: application/json

Array

eventType required	string Unique identifier of the event.
action	string Indicates whether the event should be subscribed to or unsubscribed from. Enum: "SUBSCRIBE" "UNSUBSCRIBE"
	object (Metadata for update) Auditing details.
fieldsToUnsubscribe	Array of strings Fields to exclude from notification.
fieldsToSubscribe	Array of strings Fields to re-include in the notification. To be used when user wants to subscribe to previously unsubscribed fields.

Responses

207

Multi Status response containing individual results for each subscription request.

400

Request was syntactically incorrect. Details are provided in the response payload.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match the scopes required by the endpoint.

404

The requested resource does not exist.

409

Conflict. The resource already exists.

500

Some server-side error occurred. Details are provided in the response payload.

patch/{tenant}/event-subscriptions

Request samples

application/json

[{"eventType": "product.created",
"action": "SUBSCRIBE",
"fieldsToSubscribe": ["name"
],
"fieldsToUnsubscribe": ["description"
],
"metadata": {"version": 1
}
},
{"eventType": "product.updated",
"action": "UNSUBSCRIBE",
"metadata": {"version": 2
}
}
]

Response samples

application/json

[{"eventType": "product.created",
"code": 200,
"status": "OK"
},
{"eventType": "product.updated",
"code": 200,
"status": "OK"
},
{"eventType": "product.deleted",
"code": 409,
"status": "CONFLICT",
"message": "Unique constraint violation for provided eventType and metadata version. It is possible to update an eventsubscription only by always providing the latest version. Fetch the event subscriptions to get the latest version."
}
]

Retrieving all subscriptions

Retrieves all events with associated subscription details.

Note: Events that have no past subscription information will contain empty metadata. Fields that are referenced in the 'excludedFields' array will be filtered out from the event payload. The absence of a field in 'excludedFields' means it will be automatically included in the event payload.

Required scopes

webhook.subscription_read

SecurityOAuth2

Request

path Parameters

tenant

required

string

Your Emporix tenant's name. Note: The tenant should always be written in lowercase.

header Parameters

Accept-Language

string

List of language codes acceptable for the response. You can specify factors that indicate which language should be retrieved if the one with a higher factor was not found in the localized fields. The specified languages need to be defined in the Configuration Service under project_lang key. Otherwise they will be ignored.

Note: If not specified, localized fields will be retrieved in the default language configured by the tenant in the Configuration Service.

Example: fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7

Responses

200

The request was successful. An event catalog with associated subscription details is returned.

400

Request was syntactically incorrect. Details are provided in the response payload.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match the scopes required by the endpoint.

404

The requested resource does not exist.

500

Some server-side error occurred. Details are provided in the response payload.

get/{tenant}/event-subscriptions

Request samples

Response samples

application/json

[{"event": {"type": "product.updated",
"eventSchema": {"id": "String",
"name": "LocalizedString",
"description": "LocalizedString",
"productType": "String"
},
"name": {"en": "Updated"
},
"group": {"en": "Product"
},
"description": {"en": "The event is emitted when a product is being updated."
}
},
"metadata": {"version": 1,
"createdAt": "2022-03-31T13:13:25.816Z",
"modifiedAt": "2022-03-31T13:13:25.816Z"
},
"subscription": "SUBSCRIBED",
"excludedFields": ["description"
]
}
]

Svix Emporix Shared Account

Retrieving a dashboard access URL

Retrieves a Svix magic login link (authentication embedded) and an authentication token needed to connect a tenant to their consumer application portal.

Required scopes

webhook.subscription_manage

SecurityOAuth2

Request

path Parameters

tenant

required

string

Your Emporix tenant's name.

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

Responses

200

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match the scopes required by the endpoint.

404

The requested resource does not exist.

500

Some server-side error occurred. Details are provided in the response payload.

get/{tenant}/dashboard-access

Request samples

Response samples

200
401
403
404
500

application/json

{"url": "https://app.svix.com/login#key=eyJhcHBJZCI6ICJhcHBfMXRSdFl",
"token": "appsk_kV3ts5tKPNJN4Dl25cMTfUNdmabxbX0O"
}

Retrieving webhooks statistics

Retrieves statistics on the number of emitted events and provides information on the limit of webhook notifications configured for a specific tenant.

Required scopes

webhook.subscription_read

SecurityOAuth2

Request

path Parameters

tenant

required

string

Your Emporix tenant's name.

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

query Parameters

fromYearMonth	string Month from which statistics should be retrieved. Note: The value should be provided in the "YYYY-MM" format.
toYearMonth	string Month to which statistics should be retrieved. Note: The value should be provided in the "YYYY-MM" format.

Responses

200

OK

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match the scopes required by the endpoint.

500

Some server-side error occurred. Details are provided in the response payload.

get/{tenant}/statistics

Request samples

Response samples

200
401
403
500

application/json

{"monthStatistics": [{"statisticsMonth": "2022-09",
"succesfullySentWebhooks": 8994
},
{"statisticsMonth": "2022-08",
"succesfullySentWebhooks": 2137
}
],
"webhooksLimit": 10000
}