Webhooks Setup

What Are Webhooks

Webhooks allow huhu.ai to send real-time notifications to your server when events occur, such as a try-on job completing or an image upload finishing. Instead of polling the API, your application receives an HTTP POST request the moment something happens.

This is especially useful for asynchronous workflows like batch processing, where jobs may take seconds to minutes to complete.

Configuring Endpoints

Navigate to Settings > Webhooks in the dashboard and click Add Endpoint. Provide the HTTPS URL of your server and select which events you want to subscribe to. You can add multiple endpoints for different event types.

Each endpoint is assigned a unique signing secret used to verify that incoming requests genuinely originate from huhu.ai.

Event Types

Supported events include job.completed, job.failed, image.uploaded, image.deleted, and subscription.updated. Each event payload contains a type, timestamp, and a data object with event-specific details.

Verifying Signatures

Every webhook request includes an X-HuhuAI-Signature header containing an HMAC-SHA256 signature. Compute the HMAC of the raw request body using your endpoint's signing secret and compare it to the header value. Reject any request where the signatures do not match.

Our SDKs provide a verifyWebhook() helper that handles this automatically.

Retry Policy

If your endpoint returns a non-2xx status code, huhu.ai retries the delivery up to 5 times with exponential backoff (1 s, 5 s, 30 s, 2 min, 10 min). After all retries are exhausted the event is marked as failed and visible in the webhook logs on your dashboard.