Webhooks

Webhooks

• Webhooks enable you to receive real-time notifications when your AI generation tasks are completed. Instead of continuously polling the API, you can provide a webhook URL to automatically receive a POST request with the task results.

Using Webhooks

• To integrate webhooks, include the webhook parameter in your API request. The provided URL must be an accessible HTTPS endpoint capable of handling POST requests.

Request Format

• The structure of the API request remains unchanged. Just include the webhook URL as a query parameter.

1. cURL

curl --location --request POST 'https://muapi.ai/api/v1/endpoint/generate_wan_ai_effects?webhook=https://your.app.user/endpoints' \
--header "Content-Type: application/json" \
--header "x-api-key: {MUAPIAPP_API_KEY}" \
--data-raw '{"param1": "value1", "param2": "value2"}

2. Python

import requests
import json

url = "https://muapi.ai/api/v1/endpoint/generate_wan_ai_effects"

params = {
  "webhook": "https://your.app.user/endpoints"
}

headers = {
  "x-api-key": f"{MUAPIAPP_API_KEY}",
  "Content-Type": "application/json"
}

payload = {
  "param1": "value1",
  "param2": "value2"
}

response = requests.post(url, headers=headers, params=params, json=payload)
print(response.json())

Webhook Payload

• When your webhook is triggered, it will receive a POST request containing the result of the task. The response format includes status information and relevant metadata:

  • completed: The task finished successfully and results are available.
  • failed: The task encountered an error. Details can be found in the error field.

• When your webhook endpoint is called, you’ll receive a POST request with the following structure:

  {
    "id": "<task_id>",
    "outputs": [
      "<output_url>" // Present only if the task is successful
    ],
    "urls": {
      "get": "https://api.muapi.ai/api/v1/predictions/<task_id>/result"
    },
    "has_nsfw_contents": [
      false
    ],
    "status": "completed", // or "failed"
    "created_at": "<created_at>",
    "error": "<error>", // Present if status is "failed"
    "executionTime": "<time>",
    "timings": {
      "inference": "<time>"
    }
  }
  

Best Practices

1. Use HTTPS: Always secure your webhook endpoint.
2. Implement Retry Logic: Ensure your endpoint handles temporary issues gracefully.
3. Authenticate Requests: Add verification to confirm webhook requests are legitimate.
4. Fast Response: Your endpoint should quickly return a 2xx HTTP status.
5. Ensure Idempotency: Prevent duplicated processing if a webhook is sent multiple times.

Error Handling

• If your endpoint is unreachable or returns an error, we’ll retry the webhook delivery up to three times using exponential backoff. Ensure your endpoint is resilient and capable of handling the expected request volume.