Understanding Webhooks in Audiorista

What are webhooks?

Webhooks are a way for applications to communicate with each other in real-time. Think of them as automated notifications that get sent from one system to another when specific events occur. Instead of constantly checking for updates (polling), webhooks allow Audiorista to "push" information to your application immediately when something important happens.

When an event occurs in Audiorista, we'll send an HTTP POST request to a URL you specify, containing relevant data about what just happened. This enables you to build responsive integrations that react instantly to changes in your content.

Webhook events in Audiorista

Audiorista supports three types of webhook events that you can subscribe to:

Title updated Fires whenever a Title in your project is modified. This includes changes to metadata, content, or publishing status.

Title ready Fires when a Title is both published and all of its associated Assets have been transcoded. This is particularly useful when you need to know that a Title is completely ready for end users.

Asset transcoded Triggers when an Asset has completed the transcoding process and is ready for use in your applications. Since Assets require processing before they become available, this webhook helps you know exactly when they're ready.

Setting up webhooks

To create a webhook in Audiorista:

1. If needed, install the Webhook extension in Extension > All > Webhooks
2. Navigate to Extension > Manage > Webhook
3. Choose the event type you want to monitor (Title Updated, Asset Transcoded, or Title Ready)
4. Enter the URL where you want to receive the webhook notifications
5. Save your webhook configuration

Your webhook will be created in an active state, so you are now ready to go!

Managing your webhooks

Once created, you can:

Activate/Deactivate: Toggle your webhook on or off without deleting the configuration. This is useful for maintenance or troubleshooting.

Key: Set an optional security key that will be sent with each webhook request in the X-Audiorista-Key header. This allows you to verify that requests are genuinely coming from Audiorista.

Webhook delivery

When an event occurs, Audiorista will send an HTTP POST request to your configured URL. The request will include:

• JSON payload containing event data and relevant information
• Content-Type: application/json header
• X-Audiorista-Key header (if you've configured a security key)

Your endpoint should respond with a 2xx status code to acknowledge successful receipt. If we don't receive a successful response, we may retry the delivery according to our retry policy.

{
    "id": int,
    "external_id": str,
    "uri": str,
    "name": str,
    "description": str,
    "rich_description": str,
    "share": null | {
        "url": str,
        "background_image": str
    },
    "thumbnail": str,
    "tall_thumbnail": str,
    "creator_thumbnail": str,
    "banner": str,
    "background_image": null | str,
    "video_snippet": null | str,
    "creator": str,
    "is_paid": bool,
    "created": str,
    "extra": [],
    "assets": [
        {
            "type": int,
            "order": int,
            "id": int,
            "name": str,
            "content_type": str,
            "media_type": str,
            "storage_media_type": str,
            "duration_ms": int,
            "pages": int,
            "fixed_layout": bool,
            "filesize_bytes": int,
            "download_type": str,
            "chapters": []
        }
    ],
    "tags": [  // includes private tags
        {
            "name": str,
            "slug": str
        }
    ],
    "rating": str
}

Best practices

Verify webhook authenticity: Always check the X-Audiorista-Key header if you've configured a security key to ensure requests are legitimate.

Handle retries gracefully: Make your webhook endpoint idempotent, as you may receive the same event multiple times.

Respond quickly: Keep your webhook processing lightweight and respond promptly. For heavy processing, consider queuing the work for background processing.

Test thoroughly: Use the activate/deactivate feature to test your integration before going live with webhook notifications.

Troubleshooting

If you're not receiving expected webhooks:

• Verify your webhook is activated
• Check that your endpoint URL is accessible and responding with 2xx status codes
• Ensure your server can handle HTTPS requests (if applicable)
• Review your webhook configuration to confirm you're subscribed to the correct event types

For additional support with webhooks, contact our support team with details about your specific use case and any error messages you're encountering.