Webhook

Webhooks

Overview

Receive real-time notifications from your SYNTHESIS API requests using webhooks. The SYNTHESIS Phonix service sends HTTP POST requests to your server whenever a SYNTHESIS API request is completed. Webhooks provide a seamless way to monitor the status of your requests, download/stream audio files of your AI agent, and more.

To test your webhook setup, you can use tools like RequestBin.

---

Webhook Setup

1. Register Webhook URL

To enable webhook notifications, register a webhook URL in your Service Integration settings. Ensure that:

• The URL is publicly accessible and can accept POST requests.

• Your server processes the event field in each notification to identify the type of event.

When your server receives a webhook notification, it should respond with a 200 OK status code. If your server does not respond successfully, SYNTHESIS PhonixenAI will retry the notification up to three times, with a one-hour delay between each attempt.

---

2. Verify Signature

For added security, we strongly recommend verifying the authenticity of webhook requests by validating the x-signature header. This header contains an HMAC-SHA256 hash of the request body, signed with our private key.

Example: Verifying the Signature

Download the public key from here and use the following code to verify the signature:

pythonCopy codefrom hashlib import md5
from cryptography.hazmat.primitives import hashes
from cryptography.hazmat.primitives.asymmetric import padding
from cryptography.hazmat.primitives.serialization import load_pem_public_key

def verify_signature_by_public_key(data: str, signature: bytes, public_key_path: str) -> bool:
    try:
        with open(public_key_path, "rb") as key_file:
            public_key = load_pem_public_key(key_file.read())

        event_data_hash = md5(data.encode()).digest()
        public_key.verify(
            signature,
            event_data_hash,
            padding.PKCS1v15(),
            hashes.SHA256()
        )
        return True
    except Exception as e:
        print(str(e))
        return False

result = verify_signature_by_public_key(
    data=event_uuid,
    signature=bytes.fromhex(signature),
    public_key_path="path/to/public/key/public_key.pem"
)

If the signature is invalid, do not process the request. Failing to verify signatures may result in data loss or security vulnerabilities.

---

Webhook Payload

Webhook notifications are sent as JSON objects in the body of the POST request. Each payload contains the following fields:

• event: Type of event (e.g., SYNTHESIS_SUCCESS)

• uuid: Unique identifier for the event

• data: Details of the SYNTHESIS API request

  • uuid: Identifier for the SYNTHESIS request

  • media_url: URL to download the audio file

  • synthesis_input: Text converted to speech

  • voice_id: Voice used for conversion

  • speed: Speed of the speech

  • status: Conversion status

  • model: Model used for conversion

  • used_credit: Credits consumed

  • speaker_name: Name of the voice

  • error_message: Error details (if applicable)

  • status_percentage: Completion percentage

  • created_at: Timestamp of request creation

  • updated_at: Timestamp of last update

---

Webhook Events

Notifications are triggered for the following events:

• SYNTHESIS_TEXT_SUCCESS: Sent when a SYNTHESIS text request completes successfully.

• SYNTHESIS_TEXT_FAILED: Sent when a SYNTHESIS text request fails.

• SYNTHESIS_DOCUMENT_SUCCESS: Sent when a SYNTHESIS document request completes successfully.

• SYNTHESIS_DOCUMENT_FAILED: Sent when a SYNTHESIS document request fails.

You can also trigger webhook test events directly from the Service Integration settings.