--- title: "Create Subscriptions" url: "https://stage-api-docs.centraldispatch.com/apis/stage-event-api-1-0-0/versions/c1db9b9c-04c4-43e9-9e9c-fe74c2ca0f60/operations/postCreateSubscription" --- > Full API specification: https://stage-api-docs.centraldispatch.com/apis/stage-event-api-1-0-0/versions/c1db9b9c-04c4-43e9-9e9c-fe74c2ca0f60.md # Create Subscriptions `POST` `/subscriptions` Operation ID: `postCreateSubscription` Create new event subscriptions. #### 📝 Important Notes - Creates a webhook subscription for specified event types. - The response will be empty but includes three important headers. - The `Api-Key` header value should be stored by the caller and used to authenticate all incoming events from Central Dispatch. The value will be contained in the `Api-Token` header in all events delivered as part of this subscription. - The response will contain a `Location` header that contains the fully qualified URL of the newly created resource. The final segment of the URL will be the ID of the resource. - The response will include an `ETag` header, which should be used for the `If-Match` header in subsequent updates. ## Header parameters - `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 - `201` - Created. Successful request. - `400` - Bad Request. Check the request payload. **Scenarios:** - Missing required fields. - Invalid request parameters. - `401` - Unauthorized. Authentication failed or missing. - `403` - Forbidden. The attempted action is not permitted. - `409` - Conflict. Update not allowed based on the current resource state. **Scenarios:** - Duplicate subscription attempt. - Subscription with same callback URL and event type already exists. - `422` - Unprocessable Entity. Errors found in the request. **Scenarios:** - Invalid callback URL format. - Missing required fields in subscription. - `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: post: tags: - Subscription summary: Create Subscriptions description: >- Create new event subscriptions. #### 📝 Important Notes - Creates a webhook subscription for specified event types. - The response will be empty but includes three important headers. - The `Api-Key` header value should be stored by the caller and used to authenticate all incoming events from Central Dispatch. The value will be contained in the `Api-Token` header in all events delivered as part of this subscription. - The response will contain a `Location` header that contains the fully qualified URL of the newly created resource. The final segment of the URL will be the ID of the resource. - The response will include an `ETag` header, which should be used for the `If-Match` header in subsequent updates. operationId: postCreateSubscription parameters: - 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: "`SubscriptionRequest`" content: application/json: schema: $ref: "#/components/schemas/SubscriptionRequest" examples: sample: value: callbackUrl: https://abc-trcking.net/webhook subscriptionRules: marketplaces: - "10000" eventTypes: - DispatchCreated - DispatchUpdated - DispatchAccepted responses: "201": description: Created. Successful request. headers: 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" 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" Api-Key: description: Should be stored by the caller and used to authenticate all incoming events from Central Dispatch. The value will be contained in the `Api-Token` header in all events delivered as part of this subscription. schema: type: string example: "True" "400": description: |- Bad Request. Check the request payload. **Scenarios:** - Missing required fields. - 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. "409": description: >- Conflict. Update not allowed based on the current resource state. **Scenarios:** - Duplicate subscription attempt. - Subscription with same callback URL and event type already exists. content: application/json: schema: $ref: "#/components/schemas/Errors" "422": description: |- Unprocessable Entity. Errors found in the request. **Scenarios:** - Invalid callback URL format. - Missing required fields in subscription. 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: SubscriptionRequest: 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" description: Details of a subscription. 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 ```