API for Webhooks

This page describe how to manage Webhooks via API.

Webhooks provide a way for Haut.ai to push asynchronous results back to your service once an image analysis has completed. Instead of polling the API for status, you register a callback URL and Haut.ai will notify you automatically with the outcome of the analysis.

This mechanism is ideal for workflows where you want to:

  • receive analysis results in real time,

  • keep your services responsive and efficient,

  • avoid unnecessary polling and retries.

You can also read about webhooks here.

Payload Size

Webhook requests may include analysis results directly in the payload depending on your configuration and the type of analysis performed.

  • For a single image analysis, Webhook payloads can be up to 1 MB in size.

  • For three-side analysis (Face 180), payloads can be up to 3 MB in size.

These limits are based on typical use cases and expected data volume.

What can you do?

  • Create/update a webhook destination for a dataset

Create/update a webhook destination for a dataset

Create a new webhook

post

Create a new webhook

Authorizations
AuthorizationstringRequired

Authenticate using SaaS Private token

Path parameters
company_idstring · uuidRequired
dataset_idstring · uuidRequired
Body
urlstring · uri · min: 1Required
authorizationstring · enumRequired
  • query - Query
  • basic - Basic
  • bearer - Bearer
Possible values:
authorization_keystring · min: 1 · max: 128Required
authorization_valuestring · min: 1 · max: 128Required
methodstring · enumRequired
  • post - Post
  • get - Get
Possible values:
enabledbooleanOptional
add_survey_answersbooleanOptional
merge_webhooksbooleanOptional
Responses
post
/api/v1/companies/{company_id}/datasets/{dataset_id}/webhooks/

It’s highly recommended to set up a webhook as soon as possible. Webhooks provide a more convenient and robust way to receive results for each skin analysis, using a push model for instant updates. This method is more efficient and requires fewer resources for both the client and server.

  • Webhooks are currently tied to datasets.

  • Each dataset can have only one webhook destination (this may be updated in the future).

  • Each payload includes an images object containing signed URLs. These signed URLs are temporary and will expire 1 hour after generation.

By configuring a webhook, you can automatically receive results without needing to constantly request updates.

Face Skin Metrics 2.0 webhook payload example
Recommendation Engine webhook payload example

Update webhook

If you need to update some values for webhook destination, you can just create it again (use POST method).

Authorization value

Basic authorization Webhook Request Format

When our system sends a webhook request to your specified endpoint, it will be formatted like this:

In your case, the Authorization header will contain a base64-encoded string of your credentials (in the format username:password), used for authenticating the webhook request.

Example:

If your username is username and your password is password, the encoded string will look like this:

Here, the value dXNlcm5hbWU6cGFzc3N3b3Jk is the base64-encoded version of username:password.

Explicit Authorization Value Support

Alternatively, if you prefer not to use base64 encoding, you can provide the entire Authorization value explicitly. We support both methods for flexibility in how you authenticate webhook requests from our side.

Webhook Request Format with Bearer Authorization

Our system can also send webhook requests using Bearer Token authorization. In this case, the request will be formatted like this:

Where {token} is the token you provide to authenticate the webhook request.

Example:

If your token is your_bearer_token, the request would look like this:

This method uses the Bearer scheme, which is widely used for token-based authorization, allowing secure and straightforward authentication without needing to send username and password information.

Explicit Authorization Value Support

Similar to basic authentication, we also support setting the Bearer token explicitly in the Authorization header, giving you full control over the security and flexibility of your webhook authentication method.

Receiving webhook with survey answers from Skin Consultant app

If you want to receive answers for your survey from B2C Consultant app (assuming your dataset was created for Skin Consultant app and your Skin Consultant app has survey questions), you can use the webhook setting add_survey_answers if set to true you will start receiving survey answers from your customers in the body of webhook payload.

Example survey answers

Receving webhook when all applications were calculated

If you don't want to receive webhooks with results on per-application basis, you can set the webhook setting merge_webhooks: true on webhook creation or set it when you update webhook.

If this setting is enabled, you will receive a little different payload and only when all the algorithms applications were calculated for the image.

The data structure is very similar to per-app webhooks, but here you won't have any application info and the event will be photo_calculated_by_all_apps.

Also in the area_results field you will receive area results from all algorithms within all algorithms applications connected to image's dataset.

Merged webhook example (for the Product Recommendation System 1.0 (deprecated))
Merged webhook example (for the Product Recommendation System 2.0)

If you are using the merged webhook and some algorithm wasn't calculated (due to some internal error) you will receive a webhook with partial data which was calculated at the moment in 60 seconds after image upload.

Partial merged webhook example (here we don't have re_result)
PreviousAPI for PDF reportNextAPI for SkinGPT

Last updated

Was this helpful?