--- title: "POST /eventSubscriptions" method: POST path: "/eventSubscriptions" tags: ["Event Subscriptions"] --- # POST /eventSubscriptions `POST /eventSubscriptions` Creates a new event subscription. You have the option to create a temporary subscription using server-sent events or a persistent subscription using webhooks. If you choose a temporary subscription, it will be automatically deleted if it no clients are subscribed to it for the duration specified in `timeToLiveSeconds`. If you opt for a persistent subscription, it will remain active as long as you respond to the webhook messages sent to your provided URL with a `200 OK` status. If we are unable to deliver events to your webhook continuously for 90 days, the subscription will be disabled. ## Request body - EventSubscriptionCreate - `deliveryConfig` union, required — Describes how the event subscription should deliver events to the client. - ServerSentEventsDeliveryConfigCreate - `type` 'serverSentEvents.v1', required — The type of delivery used by this subscription. New values will be added to this enum when new protocols are supported. * `serverSentEvents.v1`: The client should set-up an HTTP(S) connection to a given URL to receive events using the [Server-sent events](https://en.wikipedia.org/wiki/Server-sent_events) protocol. Currently only one client can be connected at a time to a event subscription. * `webhook.v1`: The client provides a URL to which events are pushed via HTTP POST requests when they occur. This delivery type uses the [Webhook](https://en.wikipedia.org/wiki/Webhook) method, where the server pushes the event data formatted as JSON directly to the client’s endpoint. Webhooks are suited for scenarios where the client system is capable of receiving incoming HTTP requests, allowing for real-time data delivery without the need for the client to maintain a persistent connection. - WebhookDeliveryConfigCreate - `type` 'webhook.v1', required — The type of delivery used by this subscription. New values will be added to this enum when new protocols are supported. * `serverSentEvents.v1`: The client should set-up an HTTP(S) connection to a given URL to receive events using the [Server-sent events](https://en.wikipedia.org/wiki/Server-sent_events) protocol. Currently only one client can be connected at a time to a event subscription. * `webhook.v1`: The client provides a URL to which events are pushed via HTTP POST requests when they occur. This delivery type uses the [Webhook](https://en.wikipedia.org/wiki/Webhook) method, where the server pushes the event data formatted as JSON directly to the client’s endpoint. Webhooks are suited for scenarios where the client system is capable of receiving incoming HTTP requests, allowing for real-time data delivery without the need for the client to maintain a persistent connection. - `webhookUrl` string, url, required — The HTTPS URL provided by the client where the webhook events will be sent. The client must ensure that this endpoint is configured to accept HTTPS requests and respond to an initial HTTP GET validation request. During creation, a GET request will be sent to this URL with a one-time validation token as a query parameter (`?token={validation_token}`). The endpoint must respond with a `200 OK` status and return the validation token in plain text format. The subscription will be created only if this validation succeeds. As events occur, the server will send HTTP POST requests to this URL containing the event data in JSON format. The endpoint must respond to each POST request with a `200 OK` status to acknowledge successful receipt of the event. If the endpoint fails to respond correctly after a configured number of consecutive delivery attempts for a given event, delivery of that event will be stopped to prevent further retries. If we are unable to deliver events to the webhook continuously for 90 days, the subscription will be disabled. - `technicalContactEmail` string, email, required — The email address of the technical contact responsible for managing and troubleshooting the webhook. This contact should be capable of addressing technical issues. - `technicalContactName` string, required — The name associated with the technical contact email. - `filters` FilterCreate[], required — A list of filters that determine which events will be delivered to the subscriber. Only events that match all of the conditions within a single filter will be delivered. - `actors` string[], required — List of actors for which events should be delivered to this event subscription. Actors must be specified in the format `actorType:actorId`. Wildcard Support: Use `:*` to match all actors of a specific type (e.g., `camera:*` matches all cameras). Only full wildcards (`:*`) are supported. Partial wildcards like `camera:123*` are not allowed. Only admin users can use wildcard actors. - `types` EventTypeFilter[], required — List of event types of which events should be delivered to this event subscription. - `id` string — Only events with this specific event type should be delivered to the event subscription. `GET /eventTypes` can be used to get a list of all supported event types. - `data` DslFilter — Optional DSL filter for data-level event filtering. When provided, only events whose payload matches all specified conditions are delivered to the subscription. An empty object `{}` matches all events (no filtering applied). Boolean combination keys determine how conditions are evaluated: `and` requires ALL to match, `or` requires ANY to match, `not` requires NONE to match. Arrays may contain leaf conditions or nested DslFilter objects for recursive composition. - `and` union[] — All conditions must match. Each element is a condition or nested filter. - union - DslCondition — A leaf filter condition that compares a single event data field against a value. - `field` string, required — Event data field path in the format `schema.vN.fieldName` (e.g. `een.lprDetection.v1.plate`). The special virtual field `eventType` can be used to filter by event type. - `op` 'exact' | 'ne' | 'in' | 'notIn' | 'gt' | 'gte' | 'lt' | 'lte', required — Comparison operator. Range operators (`gt`, `gte`, `lt`, `lte`) require numeric or date fields. `in` and `notIn` expect the value to be an array. - `value` union, required — The value to compare against. Must match the field type (string, number, boolean). For `in` and `notIn`, provide an array of values. - … - DslFilter — recursive - `or` union[] — At least one condition must match. Each element is a condition or nested filter. - union - DslCondition — A leaf filter condition that compares a single event data field against a value. - `field` string, required — Event data field path in the format `schema.vN.fieldName` (e.g. `een.lprDetection.v1.plate`). The special virtual field `eventType` can be used to filter by event type. - `op` 'exact' | 'ne' | 'in' | 'notIn' | 'gt' | 'gte' | 'lt' | 'lte', required — Comparison operator. Range operators (`gt`, `gte`, `lt`, `lte`) require numeric or date fields. `in` and `notIn` expect the value to be an array. - `value` union, required — The value to compare against. Must match the field type (string, number, boolean). For `in` and `notIn`, provide an array of values. - … - DslFilter — recursive - `not` union[] — None of the conditions must match. Each element is a condition or nested filter. - union - DslCondition — A leaf filter condition that compares a single event data field against a value. - `field` string, required — Event data field path in the format `schema.vN.fieldName` (e.g. `een.lprDetection.v1.plate`). The special virtual field `eventType` can be used to filter by event type. - `op` 'exact' | 'ne' | 'in' | 'notIn' | 'gt' | 'gte' | 'lt' | 'lte', required — Comparison operator. Range operators (`gt`, `gte`, `lt`, `lte`) require numeric or date fields. `in` and `notIn` expect the value to be an array. - `value` union, required — The value to compare against. Must match the field type (string, number, boolean). For `in` and `notIn`, provide an array of values. - … - DslFilter — recursive ## Response `201` EventSubscription created - EventSubscription - `id` string, required — Unique identifier of the subscriptionId. - `subscriptionConfig` EventSubscriptionConfig - `lifeCycle` 'temporary' | 'persistent' — Supported subscription lifecycles: * `temporary`: The event subscription is created by `POST /eventSubscriptions` and removed when `DELETE /eventSubscriptions/{subscriptionId}` for that subscription is called, or no client uses the subscription for the time defined in `timeToLiveSeconds`. This lifeCycle is only supported for the delivery type serverSentEvents.v1. * `persistent`: The event subscription is created by `POST /eventSubscriptions` and remains active indefinitely. It is not automatically removed based on usage or time. It must be explicitly deleted by calling `DELETE /eventSubscriptions/{subscriptionId}`. This lifeCycle is only supported for the delivery type webhook.v1. - `timeToLiveSeconds` integer — Defines the amount of time after which a `temporary` lifecycle subscription is automatically deleted if it is not being used. The determination of "usage" depends on the delivery type. For the `serverSentEvents.v1` type a subscription is marked as "in use" if a client is connected to the SSE url. For a subscription of lifeCycle type `persistent`, there is no time to live. - `deliveryConfig` union, required — Describes how the event subscription should deliver events to the client. - ServerSentEventsDeliveryConfig - `type` 'serverSentEvents.v1', required — The type of delivery used by this subscription. New values will be added to this enum when new protocols are supported. * `serverSentEvents.v1`: The client should set-up an HTTP(S) connection to a given URL to receive events using the [Server-sent events](https://en.wikipedia.org/wiki/Server-sent_events) protocol. Currently only one client can be connected at a time to a event subscription. * `webhook.v1`: The client provides a URL to which events are pushed via HTTP POST requests when they occur. This delivery type uses the [Webhook](https://en.wikipedia.org/wiki/Webhook) method, where the server pushes the event data formatted as JSON directly to the client’s endpoint. Webhooks are suited for scenarios where the client system is capable of receiving incoming HTTP requests, allowing for real-time data delivery without the need for the client to maintain a persistent connection. - `sseUrl` string, url, required — URL to be used to connect to the subscription using the server sent events protocol. Although it might look like the logic used to generate the URLs is easily implementable client-side, it could change at any point in time, so clients should always use this value instead of trying to generate it themselves. - WebhookDeliveryConfig - `type` 'webhook.v1', required — The type of delivery used by this subscription. New values will be added to this enum when new protocols are supported. * `serverSentEvents.v1`: The client should set-up an HTTP(S) connection to a given URL to receive events using the [Server-sent events](https://en.wikipedia.org/wiki/Server-sent_events) protocol. Currently only one client can be connected at a time to a event subscription. * `webhook.v1`: The client provides a URL to which events are pushed via HTTP POST requests when they occur. This delivery type uses the [Webhook](https://en.wikipedia.org/wiki/Webhook) method, where the server pushes the event data formatted as JSON directly to the client’s endpoint. Webhooks are suited for scenarios where the client system is capable of receiving incoming HTTP requests, allowing for real-time data delivery without the need for the client to maintain a persistent connection. - `webhookUrl` string, url, required — The HTTPS URL provided by the client where the webhook events will be sent. The client must ensure that this endpoint is configured to accept HTTPS requests and respond to an initial HTTP GET validation request. During creation, a GET request will be sent to this URL with a one-time validation token as a query parameter (`?token={validation_token}`). The endpoint must respond with a `200 OK` status and return the validation token in plain text format. The subscription will be created only if this validation succeeds. As events occur, the server will send HTTP POST requests to this URL containing the event data in JSON format. The endpoint must respond to each POST request with a `200 OK` status to acknowledge successful receipt of the event. If the endpoint fails to respond correctly after a configured number of consecutive delivery attempts for a given event, delivery of that event will be stopped to prevent further retries. If we are unable to deliver events to the webhook continuously for 90 days, the subscription will be disabled. - `secret` string, required — Base64 encoded secret used to sign each event sent via webhook by hashing the event with SHA-256 algorithm. ## Other responses - `400` — The supplied object is invalid. Error detail will contain the validation error. - `401` — You are not authenticated. Please authenticate and try again. - `404` — Referenced resource could not be found. - `500` — Something went wrong in the server. Please try again. --- [API](https://skmtc.net/eagleeyenetworks/apis/devices.md) · [All operations](https://skmtc.net/eagleeyenetworks/apis/devices/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/eagleeyenetworks/devices/revisions/df57313de545/schema)