Jonathon's AI Wiki

Higgsfield Webhooks

4 min read

Source: Higgsfield Docs Webhooks 2026 04 17 (Higgsfield docs — https://docs.higgsfield.ai/how-to/webhooks)

Webhooks are Higgsfield’s recommended async-result-delivery path for production apps — POST to your endpoint instead of you polling. Configuration is just a query param (hf_webhook) on the submit request. Retry window is 2 hours. Idempotency via request_id is required because retries mean duplicate deliveries are expected.

Key Takeaways

  • Configuration = one query param. Add hf_webhook=<your-endpoint-url> to your submit request URL. No separate webhook registration console step documented.
  • Three final states trigger webhooks: completed (image/video URLs in payload), failed (error message), nsfw (content-filter hit).
  • Retry for 2 hours. Higgsfield retries delivery until your endpoint returns 2xx or the 2-hour window expires.
  • Fallback if webhook fails permanently: the results are still retrievable via the status URL. Webhook is best-effort optimization, not the only delivery channel.
  • Endpoint requirements:
    • Accepts POST
    • Returns 2xx status within 10 seconds
    • Handles JSON payloads
    • Publicly accessible (no VPN-only endpoints)
    • HTTPS recommended for security
  • Idempotency is required, not optional. Retries mean duplicate deliveries are normal. Dedupe on request_id.
  • Audit logs help. Recommended practice: log every incoming webhook payload for debugging, compliance, and retry troubleshooting.

Delivery flow

Your submit request
  + hf_webhook=https://yourapp.com/webhooks/higgsfield
    ↓
  request_id returned
    ↓
  Higgsfield runs generation (queued → in_progress → final state)
    ↓
  Final state reached:
    POST → https://yourapp.com/webhooks/higgsfield
      Body: JSON with request_id + final state + urls/errors
    ↓
  Your endpoint returns 2xx in <10s
    ↓
  Delivered, done

On non-2xx or timeout: retry with exponential backoff for up to 2 hours. After 2 hours: abandon delivery; results still available at status URL.

Endpoint checklist

  • Accepts POST with JSON body
  • Publicly reachable (no firewall gotchas)
  • HTTPS with a valid cert
  • Responds 2xx within 10s on normal path
  • Idempotent — same request_id handled multiple times produces same result
  • Logs every incoming payload (debugging + audit)
  • Validates payload against expected request_id from original submit

Anti-patterns

  • Returning 4xx for known-duplicate deliveries. Retries will continue. Return 2xx for duplicates and discard the payload; idempotency belongs downstream of the webhook acknowledgment.
  • Doing expensive work inside the webhook handler. 10-second timeout. Enqueue a background job, return 200, do the work async.
  • No HTTPS in production. Both a security risk (payload tampering) and a reliability risk (some systems block plain-HTTP POSTs to unknown endpoints).
  • Dropping the request_id from your submit records. You lose the ability to correlate late deliveries with original requests.

Implementation

  • Tool/Service: Higgsfield webhook system
  • Setup: Stand up an HTTPS endpoint; add hf_webhook=<endpoint> to every submit
  • Cost: Free — no per-webhook charge documented
  • Integration notes:
    • Works alongside polling — if webhook fails, fall back to polling the status URL
    • Pairs naturally with Claude Code Routines (API trigger mode) — a Routine can receive the webhook, inspect the payload, and run downstream steps in-session
    • For Hermes Agent workflows, the webhook is the natural integration point for media-generation tasks

Open Questions

  • Payload signing / HMAC verification. The docs mention HTTPS for security but don’t document request-signing. Is there a shared-secret HMAC header for verifying payload origin?
  • Retry schedule. 2-hour window is stated, but the exponential-backoff schedule within that window isn’t documented.
  • Max payload size. Not specified. Matters for endpoints with request-body limits.
  • Content-type. JSON implied but not explicitly stated (could be application/json vs application/vnd.higgsfield+json).
  • Per-request vs per-account webhook. hf_webhook is per-request; is there an account-default setting that eliminates passing it every time?

Try It

  1. Stand up a dev endpoint with ngrok + a 10-line Flask/FastAPI app that logs the incoming body. Submit one job with hf_webhook=<ngrok-url> and watch it land.
  2. Test retries. Make the endpoint return 500 once, then 200. Confirm Higgsfield retries and succeeds.
  3. Test idempotency. Return 200 twice for the same request_id (simulating retry) — your downstream state should not duplicate.
  4. Move to production. Swap ngrok for a real HTTPS endpoint. Add logging + dedup on request_id + background-job enqueuing. Validate with 10 concurrent submits.
  5. Pair with a routine. Point the webhook at a Claude Code routine’s API endpoint (docs) and have the routine process the result in a Claude session. Closes the loop between media generation and agent workflows.

Graph View

Backlinks