# Events

## 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\`

```json
{"openapi":"3.0.0","info":{"title":"Webhook Service","version":"0.0.1"},"tags":[{"name":"Events"}],"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"}}}},"schemas":{"WebhookSubscriptions":{"title":"Webhook subscriptions","type":"array","description":"Details of the event subscription.","items":{"$ref":"#/components/schemas/WebhookSubscription"}},"WebhookSubscription":{"title":"Webhook subscription","type":"object","description":"Subscription per event.","properties":{"event":{"$ref":"#/components/schemas/WebhookEvent"},"metadata":{"$ref":"#/components/schemas/Metadata"},"subscription":{"type":"string","description":"Status of the subscription.","enum":["SUBSCRIBED","UNSUBSCRIBED","NONE"]},"excludedFields":{"type":"array","description":"If `subscription` is of type `SUBSCRIBED`, `excludedFields` will contain the list of keys from the \"event.eventSchema\" that the user has previously unsubscribed from. Note: Only root level fields are supported.","items":{"type":"string"}}}},"WebhookEvent":{"title":"Webhook event","type":"object","description":"Events that you can subscribe to.","properties":{"type":{"type":"string","description":"Unique identifier of the event."},"description":{"type":"object","description":"Map of key-value pairs containing localized descriptions of the event, which includes information on when the event is emitted.","additionalProperties":{"type":"string"}},"eventSchema":{"type":"object","description":"Schema of the event."},"name":{"type":"object","description":"Map of key-value pairs containing localized names of the event.","additionalProperties":{"type":"string"}},"group":{"type":"object","description":"Map of key-value pairs containing the localized name of a group the event belongs to.","additionalProperties":{"type":"string"}}}},"Metadata":{"title":"Metadata","description":"Auditing details.","type":"object","properties":{"createdAt":{"type":"string","description":"Date and time when the document was created.","format":"date-time"},"modifiedAt":{"type":"string","description":"Date and time when the document was last modified.","format":"date-time"},"version":{"type":"integer","description":"Version of the document.","minimum":1}}},"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"]}},"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"}}}},"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"}}}}}},"paths":{"/webhook/{tenant}/event-subscriptions":{"get":{"parameters":[{"name":"Accept-Language","in":"header","description":"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.\nThe specified languages need to be defined in the Configuration Service under `project_lang` key. Otherwise they will be ignored.\n\n**Note**: If not specified, localized fields will be retrieved in the default language configured by the tenant in the Configuration Service.\n","schema":{"type":"string"},"required":false}],"summary":"Retrieving all subscriptions","operationId":"GET-webhook-list-all-event-subscriptions","responses":{"200":{"description":"The request was successful. An event catalog with associated subscription details is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSubscriptions"}}}},"400":{"$ref":"#/components/responses/BadRequest_400"},"401":{"$ref":"#/components/responses/Unauthorized_401"},"403":{"$ref":"#/components/responses/Forbidden_403"},"404":{"$ref":"#/components/responses/NotFound_404"},"500":{"$ref":"#/components/responses/InternalServerError_500"}},"description":"Retrieves all events with associated subscription details.\n\n\n**Note**: Events that have no past subscription information will contain empty metadata.\nFields 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.\n\n***\n\n**Required scopes**\n* `webhook.subscription_read`","tags":["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\`

```json
{"openapi":"3.0.0","info":{"title":"Webhook Service","version":"0.0.1"},"tags":[{"name":"Events"}],"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":{"MultiStatus_207":{"description":"Multi Status response containing individual results for each subscription request.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/UpdateSubscriptionResponse"}}}}},"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"}}}},"NotFound_404":{"description":"The requested resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"Conflict_409":{"description":"Conflict. The resource already exists.","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":{"UpdateSubscriptionResponse":{"title":"Update subscription result response","type":"object","description":"Object containing the result of event subscription.","properties":{"eventType":{"type":"string"},"code":{"type":"integer"},"status":{"type":"string"},"message":{"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"]},"WebhookSubscriptionUpdate":{"title":"Webhook subscription update","type":"array","description":"Subscription changes.","items":{"$ref":"#/components/schemas/WebhookSubscriptionUpdateItem"}},"WebhookSubscriptionUpdateItem":{"title":"Webhook subscription update item","type":"object","description":"Object used to subscribe to/unsubscribe from an event. ","properties":{"eventType":{"type":"string","description":"Unique identifier of the event."},"action":{"type":"string","enum":["SUBSCRIBE","UNSUBSCRIBE"],"description":"Indicates whether the event should be subscribed to or unsubscribed from."},"metadata":{"$ref":"#/components/schemas/MetadataForUpdate"},"fieldsToUnsubscribe":{"type":"array","description":"Fields to exclude from notification.","items":{"type":"string"}},"fieldsToSubscribe":{"type":"array","description":"Fields to re-include in the notification. To be used when user wants to subscribe to previously unsubscribed fields.","items":{"type":"string"}}},"required":["eventType"]},"MetadataForUpdate":{"title":"Metadata for update","description":"Auditing details.","type":"object","properties":{"version":{"type":"integer","description":"Version of the document.","minimum":1}}}}},"paths":{"/webhook/{tenant}/event-subscriptions":{"patch":{"summary":"Subscribing and unsubscribing from events","operationId":"PATCH-webhook-manage-event-subscriptions","responses":{"207":{"$ref":"#/components/responses/MultiStatus_207"},"400":{"$ref":"#/components/responses/BadRequest_400"},"401":{"$ref":"#/components/responses/Unauthorized_401"},"403":{"$ref":"#/components/responses/Forbidden_403"},"404":{"$ref":"#/components/responses/NotFound_404"},"409":{"$ref":"#/components/responses/Conflict_409"},"500":{"$ref":"#/components/responses/InternalServerError_500"}},"description":"Updates the list of subscriptions by either subscribing to or unsubscribing from specified events.\n\nTo receive events with fewer fields, you can specify the names of fields that you want to exclude in the 'fieldsToUnsubscribe' array.\nTo re-include the previously excluded fields, you can provide their names in the 'fieldsToSubscribe' array.\n\n***\n\n**Required scopes**\n* `webhook.subscription_manage`","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSubscriptionUpdate"}}},"description":""},"tags":["Events"]}}}}
```