v1/subscriptions
Subscribe to events related to the given entityUrn and eventType. You must specify the delivery protocol: it can be either “WSS” for Websocket protocol delivery or “HTTPS” for Webhook protocol delivery of events.
You can specify optional parameters such as filters to match specific properties in the event in order for the event to be delivered to subscribers. Some options are only available for specific protocol values.
If the operation is successful, the response returns HTTP 200 code. The response body contains the subscription ID, subscriptionID, and optionally a channel name (for “WSS” subscriptions), channel.
If a subscription by the same user or service for the same entityUrn, eventType, protocol, filters, channel or callbackUrl already exists, the response returns a 409 conflict error.
Resource Information
| Method and URI | POST https://developer.api.autodesk.com/fevnt/v1/subscriptions |
| Authentication Context | user context optional |
| Required OAuth Scopes | data:read data:create |
| Data Format | JSON |
Request
Headers
| Authorization* string | Must be Bearer <token>, where <token> is obtained via either a two-legged or three-legged OAuth flow. |
| Content-Type* string | Must be application/json |
| x-request-id string | GUID used by the service team track the request |
| region string | Specifies the geographical location (region) of the server that the request is executed on. Default is US. |
| collection-id string | Specifies the collection ID being subscribed to. The request will be routed to the region containing the collection. The region header and region query parameter always have precedence over this header. |
| locale-container-id string | Specifies the Locale Service container ID. The request is routed to the region specified by this ID. The region header and region query parameter always have precedence over this header. |
Request
Query String Parameters
| region string | Specifies the geographical location (region) of the server that the request is executed on. Default is US. The region header also specifies the region. If you specify both, the region header has precedence. |
| locale-container-id string | Specifies the Locale Service container ID. The request is routed to the region specified by this ID. The region header and region query parameter always have precedence over this query parameter. |
Request
Body Structure
The request body is a JSON object describing the parameters of the subscription to be created.
| entityUrn* string | Entity URN to subscribe to. Entity URNs are composed of a urn: prefix followed by at least three colon-separated parts, following the format: urn:namespace:type:ID
The namespace is also referred to as the Namespace Identifier (or NID). The namespace must start and end with an alphanumeric character. namespace length must be between 2 and 32 characters. namespace may contain alphanumeric, “-”, and “.” characters. All other characters are disallowed. The remainder of the URN after the namespace is considered the Namespace Specific String (NSS) and contains the type and ID fields. The NSS complies with URN RFC 8141, except that it must contain at least two colon-separated fields, “?” characters are allowed, and R, Q, and F-components are stripped and ignored. |
| eventType* string | Event type ID for subscription. Event type IDs follow a type ID format which is composed of three sections following the format: namespace:eventType-semverVersion
The namespace field must start and end with an alphanumeric character. namespace length must be between 2 and 32 characters. namespace may contain alphanumeric, “-”, and “.” characters. All other characters are disallowed. The eventType field must be composed of alphanumeric characters with the “.” character also allowed, except at the end. eventType can also contain the wildcard character “*”. The semver field must follow semver format. See https://semver.org/ for more details. When creating a subscription, it is possible to specify a event type ID containing a wildcard pattern using the asterisk character in the eventType field only. When using wildcards, the system will attempt to match other event types and use the asterisk as a placeholder for zero or more characters to other events in the namespace. For example, a eventType of asset.* would match the asset.created, asset.updated, asset.deleted, etc. event types. It might be tempting to specify all the events in a namespace using a eventType field value containing only the asterisk character. However, note that this can result in a very large number of incoming events, depending on the entityUrn field you specified. Also note that wildcards are not supported in the entityUrn parameter. |
| permissionUrn string | Permission URN which represents the entity of the resource needed to perform permission checks during subscription. Permission URNs are entity URNs. See the entityUrn property description for the format. For Asset Graph, this parameter is required and you must provide a collection URN for the collection containing the entity specified in entityUrn. |
| customProperties object | Optional object containing properties that may be used by permission endpoints. These custom properties can be utilized in the Event Definition Object (EDO) and passed to the permissions API call. customProperties is just a property bag of key-value pairs that have no semantic meaning beyond what is defined in the permissions API call. |
| protocol* string | “WSS” (secure web sockets, delivered via PubNub) or “HTTPS” (webhooks) |
| filters array: string | Optional array of filters (JsonPath format strings) for specific property types that must match in order for the events to be delivered (can be empty). |
| callbackUrl string | When using the “HTTPS” protocol, required URL for Webhooks callback. Specifying this for other protocols is an error. The URL must have a scheme. NOTE: “localhost” as the host in the URL will not reach a service running on your local machine. |
| hookToken string | Optional parameter when using the “HTTPS” protocol to set a secret token to prevent callback spoofing. The token must be between 32 and 64 alpha-numeric characters (inclusive). When you set your secret token, Data Eventing uses it to create a hash signature for each payload. This hash signature is passed along with each request, as the header x-adsk-signature. In order to validate that the request came from the Data Events Service, subscribers compute a hash using their token and ensure that it matches the hash from the Data Events Service. Data Events Service uses an HMAC hexdigest to compute the hash. |
| channel string | Required parameter when using the “WSS” protocol that specifies the channel name on which the client receives events. You can specify this parameter to send subscribed events across multiple subscriptions to a single WSS channel. As channel names live in a global namespace, the subscriber should specify a unique channel name. This should be done in order to avoid subscribing to another client’s channel. Therefore, it is strongly suggested that the channel name include something that:
Since all users of L3 use the same subscription key, (1) is the most important as it allows Autodesk, and our message delivery provider, to distinguish your channel usage and traffic from other users of L3 via a regular expression that matches your channel pattern name. NOTE: Specifying the same channel name for multiple user’s subscriptions will not allow a user to see the messages from another user’s subscriptions, as messages are encrypted with a user-specific cipher key. Due to this reason, channel sharing across different users is not recommended. |
| subscriptionExpiry string | ISO8601 formatted date and time when the subscription should expire and automatically be deleted. For the HTTP protocol, null or not present means the subscription never expires. For the WSS protocol, a value is required. The expiry may not be more than 1 year into the future. |
Response
HTTP Status Code Summary
| 200 OK | The JSON response body contains the subscription ID, subscriptionID, and optionally a channel name (for “WSS” subscriptions), channel. |
| 400 Bad Request | Bad Request response includes title with the general reason for the failure as well as detail containing the description of the problem. When necessary, the response can include additional error details in errors array, each element of which contains both title and detail, as well as field identifying the source of the error. |
| 401 Unauthorized | Request has not been applied because it lacks valid authentication credentials for the target resource. |
| 403 Forbidden | The server understood the request but refuses to authorize it. |
| 409 Conflict | The request could not be completed due to a conflict with the current state of the resource. |
| 429 Too Many Requests | User has sent too many requests in a given amount of time. |
| 500 Internal Server Error | An unexpected error occurred on the server. |
| 503 Service Unavailable | Service temporarily unavailable. |
Response
Body Structure (200)
| subscriptionId string | |
| channel string |
Example
The JSON response body contains the subscription ID, subscriptionID, and optionally a channel name (for “WSS” subscriptions), channel.
Request
curl -v 'https://developer.api.autodesk.com/fevnt/v1/subscriptions' \
-X 'POST' \
-H 'Authorization: Bearer AuIPTf4KYLTYGVnOHQ0cuolwCW2a' \
-H 'Content-Type: application/json' \
-d '{
"entityUrn": "urn:autodesk.data.assetgraph:collection:co.oeq8pG2JQyO-TewgIWD3FQ",
"eventType": "autodesk.data.assetgraph:events.asset.updated-1.0.0",
"permissionUrn": "urn:autodesk.data.assetgraph:collection:co.oeq8pG2JQyO-TewgIWD3FQ",
"customProperties": {
"customProperty1": "value1",
"customProperty2": "value2"
},
"protocol": "WSS",
"filters": [
"$[?(@.type=='autodesk.data.assetgraph:events.space.created-1.0.0')]"
],
"callbackUrl": "https://my.callbackurl.com/somePath",
"hookToken": "8M18VVe9KcmdwharRA8t2MRhYm5XJfkI",
"channel": "MYMONIKER-C-UW2-projectAlpha-05e7522b-b70f-41d6-ba0b-1c4694c7f094",
"subscriptionExpiry": "2021-07-15T01:15:36Z"
}'
Response
{
"subscriptionId": "ed9b52fd-badc-488e-9cc0-1f53dea2b9f7",
"channel": "MYMONIKER-C-UW2-projectAlpha-05e7522b-b70f-41d6-ba0b-1c4694c7f094"
}
