--- title: "Update Subscription" url: "https://stage-api-docs.centraldispatch.com/apis/stage-event-api-1-0-0/versions/c1db9b9c-04c4-43e9-9e9c-fe74c2ca0f60/operations/putSubscription" --- > Full API specification: https://stage-api-docs.centraldispatch.com/apis/stage-event-api-1-0-0/versions/c1db9b9c-04c4-43e9-9e9c-fe74c2ca0f60.md # Update Subscription `PUT` `/subscriptions/id/{subscriptionId}` Operation ID: `putSubscription` Update a subscription. #### 📝 Important Notes - Requires the full subscription payload for updates. - Must include all existing event types plus any new ones. - The `If-Match` header is required and its value can be found in the `ETag` response header of the resource's GET by ID endpoint. ## Path parameters - `subscriptionId` (string, uuid, required) - The ID of the subscription. ## Header parameters - `If-Match` (integer, required) - This is a required field to ensure the update is being completed on an item that has not changed since it was last read. The value of this field will be the value of the `ETag` header that was received on the preceding get call. - `Content-Type` (string, required) - The major version of the API to make a request against. This is a custom MIME type that contains `vnd.coxauto.v[#]+`. For example, to request a resource from version 1.x.x of an API, the Content-Type header should be set to `application/vnd.coxauto.v1+json`. ## Request body Content types: `application/json` ## Responses - `204` - No Content. Successful request. - `400` - Bad Request. Check the request payload. **Scenarios:** - Missing `If-Match` header (required for updates). - Invalid request parameters. - `401` - Unauthorized. Authentication failed or missing. - `403` - Forbidden. The attempted action is not permitted. - `404` - Not Found. **Scenarios:** - Subscription not found. - Invalid `subscriptionId`. - `412` - Precondition Failed **Scenarios:** - `If-Match` header doesn't match current `ETag`. - Concurrent modification detected. - Resource modified by another request. - `422` - Unprocessable Entity. Errors found in the request. **Scenarios:** - Invalid callback URL in subscription. - Attempting to modify immutable fields. - `429` - Too Many Requests. Rate limit exceeded. - `500` - Error. - `503` - Service Unavailable. Temporary service interruption. ## OpenAPI definition ```yaml openapi: 3.0.1 info: title: Event API version: 1.0.0 servers: - url: https://event-api.centraldispatch.com description: Production server paths: /subscriptions/id/{subscriptionId}: put: tags: - Subscription summary: Update Subscription description: >- Update a subscription. #### 📝 Important Notes - Requires the full subscription payload for updates. - Must include all existing event types plus any new ones. - The `If-Match` header is required and its value can be found in the `ETag` response header of the resource's GET by ID endpoint. operationId: putSubscription parameters: - name: subscriptionId in: path description: The ID of the subscription. required: true schema: type: string format: uuid example: 50b2863f-c75e-45cb-8d50-b5a975d67865 - name: If-Match in: header description: This is a required field to ensure the update is being completed on an item that has not changed since it was last read. The value of this field will be the value of the `ETag` header that was received on the preceding get call. required: true schema: type: integer example: 8675309 - name: Content-Type in: header description: The major version of the API to make a request against. This is a custom MIME type that contains `vnd.coxauto.v[#]+`. For example, to request a resource from version 1.x.x of an API, the Content-Type header should be set to `application/vnd.coxauto.v1+json`. required: true schema: type: string example: application/vnd.coxauto.v1+json requestBody: description: "`UpdateSubscriptionRequest`" content: application/json: schema: $ref: "#/components/schemas/UpdateSubscriptionRequest" examples: sample: value: callbackUrl: https://abc-trcking.net/webhook subscriptionRules: marketplaces: - "10000" eventTypes: - DispatchCreated - DispatchUpdated - DispatchAccepted - DispatchVehiclePickedup - DispatchVehicleDelivered isEnabled: true responses: "204": description: No Content. Successful request. headers: Etag: description: Contains the current version of the resource and should be used for the `If-Match` header on updates. schema: type: string example: "8675300" Last-Modified: description: Last-Modified schema: type: string example: 2024-10-15T00:00:00Z Location: description: Contains the fully qualified URL of the newly created or updated resource. The final segment of the URL will equal the ID of the resource. schema: type: string example: "8675309" "400": description: |- Bad Request. Check the request payload. **Scenarios:** - Missing `If-Match` header (required for updates). - Invalid request parameters. content: application/json: schema: $ref: "#/components/schemas/Errors" "401": description: Unauthorized. Authentication failed or missing. "403": description: Forbidden. The attempted action is not permitted. "404": description: |- Not Found. **Scenarios:** - Subscription not found. - Invalid `subscriptionId`. content: application/json: schema: $ref: "#/components/schemas/Errors" "412": description: |- Precondition Failed **Scenarios:** - `If-Match` header doesn't match current `ETag`. - Concurrent modification detected. - Resource modified by another request. content: application/json: schema: $ref: "#/components/schemas/Errors" "422": description: |- Unprocessable Entity. Errors found in the request. **Scenarios:** - Invalid callback URL in subscription. - Attempting to modify immutable fields. content: application/json: schema: $ref: "#/components/schemas/Errors" "429": description: Too Many Requests. Rate limit exceeded. "500": description: Error. content: application/json: schema: $ref: "#/components/schemas/Errors" "503": description: Service Unavailable. Temporary service interruption. security: - Bearer: [] security: - Bearer: [] components: schemas: UpdateSubscriptionRequest: required: - callbackUrl - subscriptionRules type: object properties: callbackUrl: type: string description: A valid URL that you own, which will be used to receive event notifications from the Central Dispatch Event service. example: https://abc-trcking.net/webhook subscriptionRules: $ref: "#/components/schemas/SubscriptionRules" isEnabled: type: boolean description: Indicates whether the subscription is currently active. default: false example: true description: Details of update subscription request. Errors: type: object properties: errors: type: array items: $ref: "#/components/schemas/Error" description: A collection of errors. nullable: true description: An error occurred, and the request could not be completed. SubscriptionRules: required: - marketplaces - eventTypes type: object properties: marketplaces: type: array items: type: string description: A collection of Marketplaces to which the subscription applies. The caller must have access to all listed Marketplaces. example: - "10000" eventTypes: type: array items: type: string description: A collection of event types. Use the `Get Event Types` endpoint to retrieve valid values. example: - DispatchCreated - DispatchUpdated - DispatchAccepted description: Details of subscription rules. Error: type: object properties: code: type: string description: The code used for the issue. nullable: true example: resource.issue_type message: type: string description: A detailed message. nullable: true example: The issue happened because something is wrong. property: type: string description: The property to which the issue is associated. nullable: true example: person properties: type: object additionalProperties: type: string description: Additional properties related to the issue. nullable: true example: firstName: D0nn@ lastName: Sm!th description: Details of an error or issue. securitySchemes: Bearer: type: http scheme: Bearer ```