Share via

Web Hooks - Create

Service:
Azure AI Services
API Version:
v3.1

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.1/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

minLength: 1

The display name of the object.
events True

WebHookEvents

WebHookEvents
webUrl True

string (uri)

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.
links

WebHookLinks

WebHookLinks
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.1/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

Status code:
201 
Location: https://westus.api.cognitive.microsoft.com/speechtotext/v3.1/webhooks/2e856efe-ef53-465a-a632-6a084c1d349d
{
  "displayName": "TranscriptionCompletionWebHook",
  "self": "https://westus.api.cognitive.microsoft.com/speechtotext/v3.1/webhooks/2e856efe-ef53-465a-a632-6a084c1d349d",
  "links": {
    "ping": "https://westus.api.cognitive.microsoft.com/speechtotext/v3.1/webhooks/2e856efe-ef53-465a-a632-6a084c1d349d:test",
    "test": "https://westus.api.cognitive.microsoft.com/speechtotext/v3.1/webhooks/2e856efe-ef53-465a-a632-6a084c1d349d:ping"
  },
  "properties": {
    "apiVersion": "v3.1",
    "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

Enumeration

DetailedErrorCode

Value Description
InvalidParameterValue

Invalid parameter value.
InvalidRequestBodyFormat

Invalid request body format.
EmptyRequest

Empty Request.
MissingInputRecords

Missing Input Records.
InvalidDocument

Invalid Document.
ModelVersionIncorrect

Model Version Incorrect.
InvalidDocumentBatch

Invalid Document Batch.
UnsupportedLanguageCode

Unsupported language code.
DataImportFailed

Data import failed.
InUseViolation

In use violation.
InvalidLocale

Invalid locale.
InvalidBaseModel

Invalid base model.
InvalidAdaptationMapping

Invalid adaptation mapping.
InvalidDataset

Invalid dataset.
InvalidTest

Invalid test.
FailedDataset

Failed dataset.
InvalidModel

Invalid model.
InvalidTranscription

Invalid transcription.
InvalidPayload

Invalid payload.
InvalidParameter

Invalid parameter.
EndpointWithoutLogging

Endpoint without logging.
InvalidPermissions

Invalid permissions.
InvalidPrerequisite

Invalid prerequisite.
InvalidProductId

Invalid product id.
InvalidSubscription

Invalid subscription.
InvalidProject

Invalid project.
InvalidProjectKind

Invalid project kind.
InvalidRecordingsUri

Invalid recordings uri.
OnlyOneOfUrlsOrContainerOrDataset

Only one of urls or container or dataset.
ExceededNumberOfRecordingsUris

Exceeded number of recordings uris.
ModelMismatch

Model mismatch.
ProjectGenderMismatch

Project gender mismatch.
ModelDeprecated

Model deprecated.
ModelExists

Model exists.
ModelNotDeployable

Model not deployable.
EndpointNotUpdatable

Endpoint not updatable.
SingleDefaultEndpoint

Single default endpoint.
EndpointCannotBeDefault

Endpoint cannot be default.
InvalidModelUri

Invalid model uri.
SubscriptionNotFound

Subscription not found.
QuotaViolation

Quota violation.
UnsupportedDelta

Unsupported delta.
UnsupportedFilter

Unsupported filter.
UnsupportedPagination

Unsupported pagination.
UnsupportedDynamicConfiguration

Unsupported dynamic configuration.
UnsupportedOrderBy

Unsupported order by.
NoUtf8WithBom

No utf8 with bom.
ModelDeploymentNotCompleteState

Model deployment not complete state.
SkuLimitsExist

Sku limits exist.
DeployingFailedModel

Deploying failed model.
UnsupportedTimeRange

Unsupported time range.
InvalidLogDate

Invalid log date.
InvalidLogId

Invalid log id.
InvalidLogStartTime

Invalid log start time.
InvalidLogEndTime

Invalid log end time.
InvalidTopForLogs

Invalid top for logs.
InvalidSkipTokenForLogs

Invalid skip token for logs.
DeleteNotAllowed

Delete not allowed.
Forbidden

Forbidden.
DeployNotAllowed

Deploy not allowed.
UnexpectedError

Unexpected error.
InvalidCollection

Invalid collection.
InvalidCallbackUri

Invalid callback uri.
InvalidSasValidityDuration

Invalid sas validity duration.
InaccessibleCustomerStorage

Inaccessible customer storage.
UnsupportedClassBasedAdaptation

Unsupported class based adaptation.
InvalidWebHookEventKind

Invalid web hook event kind.
InvalidTimeToLive

Invalid time to live.

EntityError

Object

EntityError

Name Type Description
code

string

The code of this error.
message

string

The message for this error.

Error

Object

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

Enumeration

ErrorCode

Value Description
InvalidRequest

Representing the invalid request error code.
InvalidArgument

Representing the invalid argument error code.
InternalServerError

Representing the internal server error error code.
ServiceUnavailable

Representing the service unavailable error code.
NotFound

Representing the not found error code.
PipelineError

Representing the pipeline error error code.
Conflict

Representing the conflict error code.
InternalCommunicationFailed

Representing the internal communication failed error code.
Forbidden

Representing the forbidden error code.
NotAllowed

Representing the not allowed error code.
Unauthorized

Representing the unauthorized error code.
UnsupportedMediaType

Representing the unsupported media type error code.
TooManyRequests

Representing the too many requests error code.
UnprocessableEntity

Representing the unprocessable entity error code.

InnerError

Object

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

Enumeration

Status

Value Description
NotStarted

The long running operation has not yet started.
Running

The long running operation is currently processing.
Succeeded

The long running operation has successfully completed.
Failed

The long running operation has failed.

WebHook

Object

WebHook

Name Type Description
createdDateTime

string (date-time)

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

minLength: 1

The display name of the object.
events

WebHookEvents

WebHookEvents
lastActionDateTime

string (date-time)

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 (uri)

The location of this entity.
status

Status

Status
Describe the current state of the API
webUrl

string (uri)

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

WebHookEvents

Object

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

Object

WebHookLinks

Name Type Description
ping

string (uri)

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 (uri)

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

Object

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.