Webhooks
Webhooks are a powerful feature that allow your application to receive real-time notifications about specific events as they occur in our service. Instead of constantly polling our API to check for updates, webhooks push the data directly to your server, ensuring that you stay informed as soon as something important happens. This guide will walk you through the basics of setting up, managing, and utilizing webhooks effectively.
What are webhooks?
Webhooks are user-defined HTTP callbacks that are triggered by specific events. When such an event occurs, our server sends an HTTP POST request to the webhook's configured URL, containing a payload with relevant event data. This enables your application to respond to events in real-time, whether it's to update your database, trigger other processes, or notify users.
Why use webhooks?
Webhooks offer several advantages:
- Real-Time Notifications: Get immediate updates about important events.
- Reduced Polling: Save bandwidth and processing power by eliminating the need to constantly poll our API.
- Automated Workflows: Automatically trigger workflows or processes in your application based on the events received.
Webhook events available in our service
Our service supports three primary webhook events that you can subscribe to. Here’s an overview of each event:
1. file.received
- Description: This event is triggered when a new file is successfully uploaded and received by our service.
- Event Properties:
type: The webhook type (file.received).emitted_at: Timestamp when the event was emitted.media_id: Unique ID of the received file.media_type: Received file type (ex: video,live-stream).qualities: Received file qualities (ex: 720p,1080p).title: Received file title.status: Received file status (ex: transcoding, done, fail).user_id: Received file owner.
2. encoding.started
- Description: This event is triggered when the encoding process for a file begins.
- Event Properties:
type: The webhook type (encoding.started).emitted_at: Timestamp when the event was emitted.media_id: Unique ID of the received file.media_type: Received file type (ex: video,live-stream).qualities: Received file qualities (ex: 720p,1080p).title: Received file title.status: Received file status (ex: transcoding, done, fail).user_id: Received file owner.
3. partial.finished
- Description: This event is triggered when the encoding process for quality has been completed.
- Event Properties:
type: The webhook type (partial.finished).emitted_at: Timestamp when the event was emitted.media_id: Unique ID of the received file.media_type: Received file type (ex: video,live-stream).qualities: Encoded quality name (ex: 720p).title: Received file title.status: Received file status (ex: transcoding, done, fail).user_id: Received file owner.
4. encoding.finished
- Description: This event is triggered when the encoding process for a file is completed.
- Event Properties:
type: The webhook type (encoding.finished).emitted_at: Timestamp when the event was emitted.media_id: Unique ID of the received file.media_type: Received file type (ex: video,live-stream).qualities: Received file qualities (ex: 720p,1080p).title: Received file title.status: Received file status (ex: transcoding, done, fail).user_id: Received file owner.
5. encoding.failed
- Description: This event is triggered when the encoding process for a file has failed.
- Event Properties:
type: The webhook type (encoding.failed).emitted_at: Timestamp when the event was emitted.media_id: Unique ID of the received file.media_type: Received file type (ex: video,live-stream).qualities: Received file qualities (ex: 720p,1080p).title: Received file title.status: Received file status (ex: transcoding, done, fail).user_id: Received file owner.
Setting up webhooks
Prerequisites
Before you can create webhooks, you need to have an account on our platform. Once you’re logged in, follow these steps:
Step 1: Prepare your server
Ensure your server can handle incoming HTTP POST requests. The server should be capable of processing the JSON payload sent by our webhook events.
Step 2: Create a Webhook
To create a webhook, you'll need to specify the URL of your server that will receive the webhook notifications and the list of events you want to subscribe to.
Example: Creating a Webhook Using Curl
curl --location 'https://api.aiozstream.network/api/webhooks' \
--header 'accept: application/json' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
"file_received": false,
"encoding_started": true,
"encoding_finished": true,
"url": "string",
"name": "string"
}'
Step 3: Testing your webhook
Use testing tools like Pipedream to simulate webhook events and verify that your server correctly processes the incoming data. These tools help ensure that your webhook integration works as expected before going live. (Note: A 2xx status code response is expected from the partner backend. If the partner backend does not respond with a 2xx status code, the AIOZ Stream API will retry a few more times.)
curl --location --request POST 'https://api.aiozstream.network/api/webhooks/check/{webhook_id}' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--header 'accept: application/json'Step 4: Handling webhook events
When your server receives a webhook, it should process the JSON payload and respond with a 2xx status code to acknowledge successful receipt. If your server does not return a 2xx status code, our service will retry the webhook delivery up to three times with a 3-second interval between attempts.
Managing webhooks
Listing all webhooks
You can retrieve a list of all registered webhooks, along with their associated events and URLs, using the following request:
Example: Listing All Webhooks Using Curl
curl --location 'https://api.aiozstream.network/api/webhooks' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--header 'accept: application/json'Viewing a specific webhook
To view details about a specific webhook, including its configuration and associated events, use the unique webhook ID in your request.
Example: Viewing a Webhook Using Curl
curl --location 'https://api.aiozstream.network/api/webhooks/{webhook_id}' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--header 'accept: application/json'Deleting a webhook
If you no longer need a webhook, you can delete it using its unique ID. Be aware that this action is irreversible.
Example: Deleting a Webhook Using Curl
curl --location --request DELETE 'https://api.aiozstream.network/api/webhooks/{webhook_id}' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--header 'accept: application/json'Best practices for webhook management
- Security: Always validate the source of webhook requests by verifying signatures or using other security mechanisms to ensure the request is genuinely from our service.
- Idempotency: Ensure your webhook handler can safely process the same event multiple times, as retries can lead to duplicate events.
- Logging: Keep logs of received webhooks and your server's responses for troubleshooting and audit purposes.
- Timeouts: Design your webhook handler to respond quickly—ideally within a few seconds—to avoid timeouts and retry attempts.
- Rate Limiting: Implement rate limiting on your server to handle potential bursts of webhook events without overwhelming your infrastructure.
Next steps
Explore more advanced features of our API, including setting up specific filters for webhooks, integrating with third-party services, and handling complex event-driven workflows. Visit our API documentation for more detailed guidance.
FAQs
Q: How do I verify that a webhook request is from your service?
A: You
can verify webhook requests by checking the request headers for a signature or
token that matches the one provided by our service.
Q: What happens if my server is down when a webhook is sent?
A: Our
webhook service will retry the request up to three times at 3-second intervals
if your server does not respond with a 2xx status code.
Q: Can I change the URL for an existing webhook?
A: Yes, you can update
the webhook configuration by making a PUT request to the webhook endpoint with
the new URL.