Web Hooks - Create

Creates a new web hook.
If the property secret in the configuration is present and contains a non-empty string, it will be used to create a SHA256 hash of the payload with the secret as HMAC key. This hash will be set as X-MicrosoftSpeechServices-Signature header when calling back into the registered URL.

When calling back into the registered URL, the request will contain a X-MicrosoftSpeechServices-Event header containing one of the registered event types. There will be one request per registered event type.

After successfully registering the web hook, it will not be usable until a challenge/response is completed. To do this, a request with the event type challenge will be made with a query parameter called validationToken. Respond to the challenge with a 200 OK containing the value of the validationToken query parameter as the response body. When the challenge/response is successfully completed, the web hook will begin receiving events.

POST {endpoint}/speechtotext/v3.2-preview.2/webhooks

URI Parameters

Name In Required Type Description
endpoint
path True

string

Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com).

Request Body

Name Required Type Description
displayName True

string

The display name of the object.

events True

WebHookEvents

WebHookEvents

webUrl True

string

The registered URL that will be used to send the POST requests for the registered events to.

customProperties

object

The custom properties of this entity. The maximum allowed key length is 64 characters, the maximum allowed value length is 256 characters and the count of allowed entries is 10.

description

string

The description of the object.

properties

WebHookProperties

WebHookProperties

Responses

Name Type Description
201 Created

WebHook

The response contains information about the entity as payload and its location as header.

Headers

Location: string

Other Status Codes

Error

An error occurred.

Security

Ocp-Apim-Subscription-Key

Provide your cognitive services account key here.

Type: apiKey
In: header

Authorization

Provide an access token from the JWT returned by the STS of this region. Make sure to add the management scope to the token by adding the following query string to the STS URL: ?scope=speechservicesmanagement

Type: apiKey
In: header

Examples

Create a web hook

Sample request

POST {endpoint}/speechtotext/v3.2-preview.2/webhooks

{
  "displayName": "TranscriptionCompletionWebHook",
  "properties": {
    "secret": "$CREDENTIAL_PLACEHOLDER$"
  },
  "webUrl": "https://contoso.com/call/me/back",
  "events": {
    "transcriptionCompletion": true
  },
  "description": "I registered this URL to get a POST request for each completed transcription."
}

Sample response

Location: https://westus.api.cognitive.microsoft.com/speechtotext/v3.2-preview.2/webhooks/2e856efe-ef53-465a-a632-6a084c1d349d
{
  "displayName": "TranscriptionCompletionWebHook",
  "self": "https://westus.api.cognitive.microsoft.com/speechtotext/v3.2-preview.2/webhooks/2e856efe-ef53-465a-a632-6a084c1d349d",
  "links": {
    "ping": "https://westus.api.cognitive.microsoft.com/speechtotext/v3.2-preview.2/webhooks/2e856efe-ef53-465a-a632-6a084c1d349d:test",
    "test": "https://westus.api.cognitive.microsoft.com/speechtotext/v3.2-preview.2/webhooks/2e856efe-ef53-465a-a632-6a084c1d349d:ping"
  },
  "properties": {
    "apiVersion": "v3.2-preview.2",
    "secret": "$CREDENTIAL_PLACEHOLDER$"
  },
  "webUrl": "https://contoso.com/call/me/back",
  "events": {
    "transcriptionCompletion": true
  },
  "description": "I registered this URL to get a POST request for each completed transcription.",
  "createdDateTime": "2018-11-11T00:00:00Z",
  "lastActionDateTime": "2018-11-28T00:00:00Z",
  "status": "NotStarted"
}

Definitions

Name Description
DetailedErrorCode

DetailedErrorCode

EntityError

EntityError

Error

Error

ErrorCode

ErrorCode

InnerError

InnerError

Status

Status

WebHook

WebHook

WebHookEvents

WebHookEvents

WebHookLinks

WebHookLinks

WebHookProperties

WebHookProperties

DetailedErrorCode

DetailedErrorCode

Name Type Description
DataImportFailed

string

Data import failed.

DeleteNotAllowed

string

Delete not allowed.

DeployNotAllowed

string

Deploy not allowed.

DeployingFailedModel

string

Deploying failed model.

EmptyRequest

string

Empty Request.

EndpointCannotBeDefault

string

Endpoint cannot be default.

EndpointNotUpdatable

string

Endpoint not updatable.

EndpointWithoutLogging

string

Endpoint without logging.

ExceededNumberOfRecordingsUris

string

Exceeded number of recordings uris.

FailedDataset

string

Failed dataset.

Forbidden

string

Forbidden.

InUseViolation

string

In use violation.

InaccessibleCustomerStorage

string

Inaccessible customer storage.

InvalidAdaptationMapping

string

Invalid adaptation mapping.

InvalidBaseModel

string

Invalid base model.

InvalidCallbackUri

string

Invalid callback uri.

InvalidCollection

string

Invalid collection.

InvalidDataset

string

Invalid dataset.

InvalidDocument

string

Invalid Document.

InvalidDocumentBatch

string

Invalid Document Batch.

InvalidLocale

string

Invalid locale.

InvalidLogDate

string

Invalid log date.

InvalidLogEndTime

string

Invalid log end time.

InvalidLogId

string

Invalid log id.

InvalidLogStartTime

string

Invalid log start time.

InvalidModel

string

Invalid model.

InvalidModelUri

string

Invalid model uri.

InvalidParameter

string

Invalid parameter.

InvalidParameterValue

string

Invalid parameter value.

InvalidPayload

string

Invalid payload.

InvalidPermissions

string

Invalid permissions.

InvalidPrerequisite

string

Invalid prerequisite.

InvalidProductId

string

Invalid product id.

InvalidProject

string

Invalid project.

InvalidProjectKind

string

Invalid project kind.

InvalidRecordingsUri

string

Invalid recordings uri.

InvalidRequestBodyFormat

string

Invalid request body format.

InvalidSasValidityDuration

string

Invalid sas validity duration.

InvalidSkipTokenForLogs

string

Invalid skip token for logs.

InvalidSourceAzureResourceId

string

Invalid source Azure resource ID.

InvalidSubscription

string

Invalid subscription.

InvalidTest

string

Invalid test.

InvalidTimeToLive

string

Invalid time to live.

InvalidTopForLogs

string

Invalid top for logs.

InvalidTranscription

string

Invalid transcription.

InvalidWebHookEventKind

string

Invalid web hook event kind.

MissingInputRecords

string

Missing Input Records.

ModelCopyOperationExists

string

Model copy operation exists.

ModelDeploymentNotCompleteState

string

Model deployment not complete state.

ModelDeprecated

string

Model deprecated.

ModelExists

string

Model exists.

ModelMismatch

string

Model mismatch.

ModelNotDeployable

string

Model not deployable.

ModelVersionIncorrect

string

Model Version Incorrect.

NoUtf8WithBom

string

No utf8 with bom.

OnlyOneOfUrlsOrContainerOrDataset

string

Only one of urls or container or dataset.

ProjectGenderMismatch

string

Project gender mismatch.

QuotaViolation

string

Quota violation.

SingleDefaultEndpoint

string

Single default endpoint.

SkuLimitsExist

string

Sku limits exist.

SubscriptionNotFound

string

Subscription not found.

UnexpectedError

string

Unexpected error.

UnsupportedClassBasedAdaptation

string

Unsupported class based adaptation.

UnsupportedDelta

string

Unsupported delta.

UnsupportedDynamicConfiguration

string

Unsupported dynamic configuration.

UnsupportedFilter

string

Unsupported filter.

UnsupportedLanguageCode

string

Unsupported language code.

UnsupportedOrderBy

string

Unsupported order by.

UnsupportedPagination

string

Unsupported pagination.

UnsupportedTimeRange

string

Unsupported time range.

EntityError

EntityError

Name Type Description
code

string

The code of this error.

message

string

The message for this error.

Error

Error

Name Type Description
code

ErrorCode

ErrorCode
High level error codes.

details

Error[]

Additional supportive details regarding the error and/or expected policies.

innerError

InnerError

InnerError
New Inner Error format which conforms to Cognitive Services API Guidelines which is available at https://microsoft.sharepoint.com/%3Aw%3A/t/CognitiveServicesPMO/EUoytcrjuJdKpeOKIK_QRC8BPtUYQpKBi8JsWyeDMRsWlQ?e=CPq8ow. This contains required properties ErrorCode, message and optional properties target, details(key value pair), inner error(this can be nested).

message

string

High level error message.

target

string

The source of the error. For example it would be "documents" or "document id" in case of invalid document.

ErrorCode

ErrorCode

Name Type Description
Conflict

string

Representing the conflict error code.

Forbidden

string

Representing the forbidden error code.

InternalCommunicationFailed

string

Representing the internal communication failed error code.

InternalServerError

string

Representing the internal server error error code.

InvalidArgument

string

Representing the invalid argument error code.

InvalidRequest

string

Representing the invalid request error code.

NotAllowed

string

Representing the not allowed error code.

NotFound

string

Representing the not found error code.

PipelineError

string

Representing the pipeline error error code.

ServiceUnavailable

string

Representing the service unavailable error code.

TooManyRequests

string

Representing the too many requests error code.

Unauthorized

string

Representing the unauthorized error code.

UnprocessableEntity

string

Representing the unprocessable entity error code.

UnsupportedMediaType

string

Representing the unsupported media type error code.

InnerError

InnerError

Name Type Description
code

DetailedErrorCode

DetailedErrorCode
Detailed error code enum.

details

object

Additional supportive details regarding the error and/or expected policies.

innerError

InnerError

InnerError
New Inner Error format which conforms to Cognitive Services API Guidelines which is available at https://microsoft.sharepoint.com/%3Aw%3A/t/CognitiveServicesPMO/EUoytcrjuJdKpeOKIK_QRC8BPtUYQpKBi8JsWyeDMRsWlQ?e=CPq8ow. This contains required properties ErrorCode, message and optional properties target, details(key value pair), inner error(this can be nested).

message

string

High level error message.

target

string

The source of the error. For example it would be "documents" or "document id" in case of invalid document.

Status

Status

Name Type Description
Failed

string

The long running operation has failed.

NotStarted

string

The long running operation has not yet started.

Running

string

The long running operation is currently processing.

Succeeded

string

The long running operation has successfully completed.

WebHook

WebHook

Name Type Description
createdDateTime

string

The time-stamp when the object was created. The time stamp is encoded as ISO 8601 date and time format ("YYYY-MM-DDThh:mm:ssZ", see https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations).

customProperties

object

The custom properties of this entity. The maximum allowed key length is 64 characters, the maximum allowed value length is 256 characters and the count of allowed entries is 10.

description

string

The description of the object.

displayName

string

The display name of the object.

events

WebHookEvents

WebHookEvents

lastActionDateTime

string

The time-stamp when the current status was entered. The time stamp is encoded as ISO 8601 date and time format ("YYYY-MM-DDThh:mm:ssZ", see https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations).

links

WebHookLinks

WebHookLinks

properties

WebHookProperties

WebHookProperties

self

string

The location of this entity.

status

Status

Status
Describe the current state of the API

webUrl

string

The registered URL that will be used to send the POST requests for the registered events to.

WebHookEvents

WebHookEvents

Name Type Description
challenge

boolean

datasetCompletion

boolean

datasetCreation

boolean

datasetDeletion

boolean

datasetProcessing

boolean

endpointCompletion

boolean

endpointCreation

boolean

endpointDeletion

boolean

endpointProcessing

boolean

evaluationCompletion

boolean

evaluationCreation

boolean

evaluationDeletion

boolean

evaluationProcessing

boolean

modelCompletion

boolean

modelCreation

boolean

modelDeletion

boolean

modelProcessing

boolean

ping

boolean

transcriptionCompletion

boolean

transcriptionCreation

boolean

transcriptionDeletion

boolean

transcriptionProcessing

boolean

WebHookLinks

Name Type Description
ping

string

The URL that can be used to trigger the sending of a ping event to the registered URL of a web hook registration. See operation "WebHooks_Ping" for more details.

test

string

The URL that can be used sending test events to the registered URL of a web hook registration. See operation "WebHooks_Test" for more details.

WebHookProperties

WebHookProperties

Name Type Description
apiVersion

string

The API version the web hook was created in. This defines the shape of the payload in the callbacks. If the payload type is not supported anymore, because the shape changed and the API version using it is removed (after deprecation), the web hook will be disabled.

error

EntityError

EntityError

secret

string

A secret that will be used to create a SHA256 hash of the payload with the secret as HMAC key. This hash will be set as X-MicrosoftSpeechServices-Signature header when calling back into the registered URL.