Register a callback.

        Registers a callback URL with the service for use with subsequent asynchronous
        recognition requests. The service attempts to register, or white-list, the
        callback URL if it is not already registered by sending a `GET` request to the
        callback URL. The service passes a random alphanumeric challenge string via the
        `challenge_string` parameter of the request. The request includes an `Accept`
        header that specifies `text/plain` as the required response type.
        To be registered successfully, the callback URL must respond to the `GET` request
        from the service. The response must send status code 200 and must include the
        challenge string in its body. Set the `Content-Type` response header to
        `text/plain`. Upon receiving this response, the service responds to the original
        registration request with response code 201.
        The service sends only a single `GET` request to the callback URL. If the service
        does not receive a reply with a response code of 200 and a body that echoes the
        challenge string sent by the service within five seconds, it does not white-list
        the URL; it instead sends status code 400 in response to the **Register a
        callback** request. If the requested callback URL is already white-listed, the
        service responds to the initial registration request with response code 200.
        If you specify a user secret with the request, the service uses it as a key to
        calculate an HMAC-SHA1 signature of the challenge string in its response to the
        `POST` request. It sends this signature in the `X-Callback-Signature` header of
        its `GET` request to the URL during registration. It also uses the secret to
        calculate a signature over the payload of every callback notification that uses
        the URL. The signature provides authentication and data integrity for HTTP
        communications.
        After you successfully register a callback URL, you can use it with an indefinite
        number of recognition requests. You can register a maximum of 20 callback URLS in
        a one-hour span of time.
        **See also:** [Registering a callback
        URL](https://cloud.ibm.com/docs/services/speech-to-text/async.html#register).

        :param str callback_url: An HTTP or HTTPS URL to which callback notifications are
        to be sent. To be white-listed, the URL must successfully echo the challenge
        string during URL verification. During verification, the client can also check the
        signature that the service sends in the `X-Callback-Signature` header to verify
        the origin of the request.
        :param str user_secret: A user-specified string that the service uses to generate
        the HMAC-SHA1 signature that it sends via the `X-Callback-Signature` header. The
        service includes the header during URL verification and with every notification
        sent to the callback URL. It calculates the signature over the payload of the
        notification. If you omit the parameter, the service does not send the header.
        :param dict headers: A `dict` containing the request headers
        :return: A `DetailedResponse` containing the result, headers and HTTP status code.
        :rtype: DetailedResponse

def register_callback(self, callback_url, user_secret=None, **kwargs):
        """
        Register a callback.

        Registers a callback URL with the service for use with subsequent asynchronous
        recognition requests. The service attempts to register, or white-list, the
        callback URL if it is not already registered by sending a `GET` request to the
        callback URL. The service passes a random alphanumeric challenge string via the
        `challenge_string` parameter of the request. The request includes an `Accept`
        header that specifies `text/plain` as the required response type.
        To be registered successfully, the callback URL must respond to the `GET` request
        from the service. The response must send status code 200 and must include the
        challenge string in its body. Set the `Content-Type` response header to
        `text/plain`. Upon receiving this response, the service responds to the original
        registration request with response code 201.
        The service sends only a single `GET` request to the callback URL. If the service
        does not receive a reply with a response code of 200 and a body that echoes the
        challenge string sent by the service within five seconds, it does not white-list
        the URL; it instead sends status code 400 in response to the **Register a
        callback** request. If the requested callback URL is already white-listed, the
        service responds to the initial registration request with response code 200.
        If you specify a user secret with the request, the service uses it as a key to
        calculate an HMAC-SHA1 signature of the challenge string in its response to the
        `POST` request. It sends this signature in the `X-Callback-Signature` header of
        its `GET` request to the URL during registration. It also uses the secret to
        calculate a signature over the payload of every callback notification that uses
        the URL. The signature provides authentication and data integrity for HTTP
        communications.
        After you successfully register a callback URL, you can use it with an indefinite
        number of recognition requests. You can register a maximum of 20 callback URLS in
        a one-hour span of time.
        **See also:** [Registering a callback
        URL](https://cloud.ibm.com/docs/services/speech-to-text/async.html#register).

        :param str callback_url: An HTTP or HTTPS URL to which callback notifications are
        to be sent. To be white-listed, the URL must successfully echo the challenge
        string during URL verification. During verification, the client can also check the
        signature that the service sends in the `X-Callback-Signature` header to verify
        the origin of the request.
        :param str user_secret: A user-specified string that the service uses to generate
        the HMAC-SHA1 signature that it sends via the `X-Callback-Signature` header. The
        service includes the header during URL verification and with every notification
        sent to the callback URL. It calculates the signature over the payload of the
        notification. If you omit the parameter, the service does not send the header.
        :param dict headers: A `dict` containing the request headers
        :return: A `DetailedResponse` containing the result, headers and HTTP status code.
        :rtype: DetailedResponse
        """

        if callback_url is None:
            raise ValueError('callback_url must be provided')

        headers = {}
        if 'headers' in kwargs:
            headers.update(kwargs.get('headers'))
        sdk_headers = get_sdk_headers('speech_to_text', 'V1',
                                      'register_callback')
        headers.update(sdk_headers)

        params = {'callback_url': callback_url, 'user_secret': user_secret}

        url = '/v1/register_callback'
        response = self.request(
            method='POST',
            url=url,
            headers=headers,
            params=params,
            accept_json=True)
        return response