Webhooks

Aana provides a webhook system that allows you to receive real-time notifications for key task events. This is particularly useful for integrating Aana with your existing workflows.

Overview

Webhooks are HTTP callbacks that are triggered by specific events in the Aana system. When an event occurs, Aana sends a POST request to the specified webhook URL with details about the event.

Currently, Aana supports the following events:

• task.completed: Triggered when a task is completed successfully.
• task.failed: Triggered when a task fails.
• task.started: Triggered when a task starts processing.

Webhook Endpoints

Refer to the following endpoints for managing webhooks:

• GET /webhooks: List all registered webhooks.
• POST /webhooks: Create a new webhook.
• GET /webhooks/{webhook_id}: Retrieve a specific webhook by its ID.
• PUT /webhooks/{webhook_id}: Update a specific webhook by its ID.
• DELETE /webhooks/{webhook_id}: Delete a specific webhook by its ID.

Webhook Validation

To ensure the integrity of the webhook data and to prevent potential spoofing, Aana uses HMAC (Hash-based Message Authentication Code) for validating webhook requests. Each webhook request includes a signature in the headers that you can use to verify the authenticity of the request.

You can find the HMAC secret in the Developers Settings section in the Aana Platform. This secret is used to generate the HMAC signature for the webhook payload.

Here is an example of how to validate the HMAC signature in Python:

import hmac
import hashlib
import json

request = ...  # The incoming request object
payload = request.json
secret_key = "YOUR_HMAC_SECRET"
signature = request.headers.get("X-Signature")
payload_str = json.dumps(payload, separators=(",", ":"))
actual_signature = hmac.new(
    secret_key.encode(), payload_str.encode(), hashlib.sha256
).hexdigest()
assert signature == actual_signature