Skip to main content

​
Overview

Webhooks allow you to receive automatic notifications when your generation requests reach a final status. Instead of polling the status endpoint, the Higgsfield API will send an HTTP POST request to your specified webhook URL.

​
Configuration

To enable webhook notifications, include the hf_webhook query parameter in your generation request with your webhook endpoint URL.

​
Example Request

curl -X POST 'https://platform.higgsfield.ai/higgsfield-ai/soul/standard?hf_webhook=https://webhook.url/example' \
  --header 'Authorization: Key {your_api_key}:{your_api_key_secret}' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "prompt": "your prompt here",
    "aspect_ratio": "16:9",
    "resolution": "720p"
  }'

​
Webhook Notifications

Your webhook endpoint will receive an HTTP POST request when the generation reaches a final status: completed, failed, or nsfw.

​
Completed Status

​
Image Generation

{
  "status": "completed",
  "request_id": "9417a243-e457-4075-895b-b68f3cda5303",
  "status_url": "https://platform.higgsfield.ai/requests/9417a243-e457-4075-895b-b68f3cda5303/status",
  "cancel_url": "https://platform.higgsfield.ai/requests/9417a243-e457-4075-895b-b68f3cda5303/cancel",
  "images": [
    {
      "url": "https://images.url/example"
    }
  ]
}

​
Video Generation

{
  "status": "completed",
  "request_id": "9417a243-e457-4075-895b-b68f3cda5303",
  "status_url": "https://platform.higgsfield.ai/requests/9417a243-e457-4075-895b-b68f3cda5303/status",
  "cancel_url": "https://platform.higgsfield.ai/requests/9417a243-e457-4075-895b-b68f3cda5303/cancel",
  "video": {
    "url": "https://video.url/example"
  }
}

​
Failed Status

{
  "status": "failed",
  "request_id": "9417a243-e457-4075-895b-b68f3cda5303",
  "error": "Generation fail message"
}

​
NSFW Status

{
  "status": "nsfw",
  "request_id": "9417a243-e457-4075-895b-b68f3cda5303"
}

​
Retry Logic

The Higgsfield API implements automatic retry logic to ensure reliable webhook delivery:
  • Webhooks will be retried for up to 2 hours after the initial delivery attempt
  • Retries continue until your endpoint returns a successful response (HTTP 2xx status code)
  • If your endpoint remains unavailable or continues to return error responses after 2 hours, retry attempts will cease
  • You can still retrieve the generation results by polling the status_url if webhook delivery fails

​
Handling Retries

To minimize unnecessary retries:
  • Ensure your webhook endpoint is highly available
  • Return a 2xx status code promptly upon successful receipt
  • Implement idempotency using the request_id to handle duplicate notifications
  • Log received webhooks to track delivery patterns

​
Webhook Requirements

  • Your webhook endpoint must accept HTTP POST requests
  • Your endpoint should respond with a 2xx status code to acknowledge receipt
  • The webhook payload will be sent as JSON in the request body
  • Ensure your endpoint is publicly accessible and can handle the expected request volume

​
Best Practices

  • Implement proper error handling for webhook deliveries
  • Validate the request_id to ensure the notification matches your records
  • Store webhook payloads for audit and debugging purposes
  • Use HTTPS endpoints for secure data transmission
  • Respond quickly to webhook requests (under 10 seconds) to avoid timeouts
  • Implement idempotency checks to safely handle duplicate webhook deliveries during retries