---
title: "Creates a new web hook."
method: POST
path: "/webhooks"
tags: ["Custom Speech web hooks:"]
---

# Creates a new web hook.

`POST /webhooks`

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.

## Request body

- WebHook
  - `webUrl` string, uri, required — The registered URL that will be used to send the POST requests for the registered events to.
  - `links` WebHookLinks
    - `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.
  - `properties` WebHookProperties
    - `error` EntityError
      - `code` string — The code of this error.
      - `message` string — The message for this error.
    - `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.
    - `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.
  - `self` string, uri — The location of this entity.
  - `displayName` string, required — The display name of the object.
  - `description` string — The description of the object.
  - `events` WebHookEvents, required
    - `datasetCreation` boolean
    - `datasetProcessing` boolean
    - `datasetCompletion` boolean
    - `datasetDeletion` boolean
    - `modelCreation` boolean
    - `modelProcessing` boolean
    - `modelCompletion` boolean
    - `modelDeletion` boolean
    - `evaluationCreation` boolean
    - `evaluationProcessing` boolean
    - `evaluationCompletion` boolean
    - `evaluationDeletion` boolean
    - `transcriptionCreation` boolean
    - `transcriptionProcessing` boolean
    - `transcriptionCompletion` boolean
    - `transcriptionDeletion` boolean
    - `endpointCreation` boolean
    - `endpointProcessing` boolean
    - `endpointCompletion` boolean
    - `endpointDeletion` boolean
    - `ping` boolean
    - `challenge` boolean
  - `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).
  - `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).
  - `status` 'NotStarted' | 'Running' | 'Succeeded' | 'Failed' — Describe the current state of the API
  - `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.

## Response `201`

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

- WebHook
  - `webUrl` string, uri, required — The registered URL that will be used to send the POST requests for the registered events to.
  - `links` WebHookLinks
    - `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.
  - `properties` WebHookProperties
    - `error` EntityError
      - `code` string — The code of this error.
      - `message` string — The message for this error.
    - `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.
    - `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.
  - `self` string, uri — The location of this entity.
  - `displayName` string, required — The display name of the object.
  - `description` string — The description of the object.
  - `events` WebHookEvents, required
    - `datasetCreation` boolean
    - `datasetProcessing` boolean
    - `datasetCompletion` boolean
    - `datasetDeletion` boolean
    - `modelCreation` boolean
    - `modelProcessing` boolean
    - `modelCompletion` boolean
    - `modelDeletion` boolean
    - `evaluationCreation` boolean
    - `evaluationProcessing` boolean
    - `evaluationCompletion` boolean
    - `evaluationDeletion` boolean
    - `transcriptionCreation` boolean
    - `transcriptionProcessing` boolean
    - `transcriptionCompletion` boolean
    - `transcriptionDeletion` boolean
    - `endpointCreation` boolean
    - `endpointProcessing` boolean
    - `endpointCompletion` boolean
    - `endpointDeletion` boolean
    - `ping` boolean
    - `challenge` boolean
  - `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).
  - `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).
  - `status` 'NotStarted' | 'Running' | 'Succeeded' | 'Failed' — Describe the current state of the API
  - `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.

## Other responses

- `default` — An error occurred.

---

[API](https://skmtc.net/azure/apis/cognitiveservices-speech-speechtotext.md) · [All operations](https://skmtc.net/azure/apis/cognitiveservices-speech-speechtotext/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/azure/cognitiveservices-speech-speechtotext/revisions/931821089e0d/schema)