> For the complete documentation index, see [llms.txt](https://docs.saas.haut.ai/haut.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.saas.haut.ai/haut.ai/developers/saas-api-overview/api-for-webhooks.md). # 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](/haut.ai/haut.ai-features/consumer-apps/make-real-time-data-connection-with-external-platforms-via-webhooks.md). ## 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 {% openapi src="/files/YmTvOjpvwq9jx4lAuJV9" path="/api/v1/companies/{company\_id}/datasets/{dataset\_id}/webhooks/" method="post" %} [openapi.json](https://245161714-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MWxBX_zB4FnflOpyBGO%2Fuploads%2FRF3DdAp7DPLxOGdzKdfj%2Fopenapi.json?alt=media\&token=805fe368-c61f-4e86-bf72-e2de9d7d6e61) {% endopenapi %} 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. ```json { "images": { "original": { "signed_url": "https://..." }, "restored": { "signed_url": "https://..." } } ``` By configuring a webhook, you can automatically receive results without needing to constantly request updates.
Face Skin Metrics 2.0 webhook payload example ```json { "application_id": "0ab53382-a1df-4733-94da-308b3d2e6db1", "application_name": "Face Skin Metrics 2.0", "application_run_id": "a966897b-3999-44fd-b9e5-73eae50bf421", "images": { "original": { "signed_url": "https://..." }, "restored": { "signed_url": "https://..." } }, "area_results": [ { "area_name": "face", "name": "Skin tone", "sub_metrics": [], "tech_name": "skintone_class", "value": "Light", "widget_meta": null, "widget_type": "category" }, { "area_name": "face", "name": "Eye Age", "sub_metrics": [], "tech_name": "eye_age", "value": 38, "widget_meta": null, "widget_type": "numeric" }, { "area_name": "left_eye_area", "name": "Left Eye Age", "sub_metrics": [], "tech_name": "left_eye_age", "value": 39, "widget_meta": null, "widget_type": "numeric" } ], "batch_id": "d57a6cc9-3628-433d-a1d8-5183e81c1c76", "company_id": "42872ecf-1734-473d-8883-9d731cbe1a2a", "dataset_id": "80f3ff87-231e-4ed7-920e-71cb9ceba49f", "event": "photo_calculated_by_app", "idempotency_id": "a39ca5f0-9e11-4c54-84bc-840beee0f768", "image_id": "ef56960f-e690-4279-8d7b-3a3842cafcb2", "image_meta": { "image_source": "native" }, "re_result": null, "subject_id": "eecbfb20-3336-4f11-bab2-cac6d1f5f850", "subject_meta": {}, "subject_name": "ivt9fwH3aTCUYXxPVPsqtk", "survey_answers": [ { "answer_id": "25fd7fc4-4a2a-46ee-b031-d75242cc516f", "answer_values": [ "1" ], "question_id": "8f9eb8dd-0c0a-4776-a3cc-291704645370", "question_text": "1" }, { "answer_id": "6bc782e5-696c-4bec-a768-edf91a1430d4", "answer_values": [ "02" ], "question_id": "a0fded87-389a-40fc-a6c2-9d79ffcb014c", "question_text": "2" }, { "answer_id": "58bd4c3d-2808-4834-8de2-1c14969227d8", "answer_values": [ "2", "3", "1" ], "question_id": "8bb18cd8-b933-4181-aca1-14c2baf3a14b", "question_text": "3" } ] } ```
Recommendation Engine webhook payload example ```json { "application_id": "fc9cb756-7bc6-492b-a058-548ed7053e2b", "application_name": "Recommendation Engine", "application_run_id": "a1066a62-f147-4a66-a095-ad08f2f39bbf", "area_results": [], "batch_id": "d57a6cc9-3628-433d-a1d8-5183e81c1c76", "company_id": "42872ecf-1734-473d-8883-9d731cbe1a2a", "dataset_id": "80f3ff87-231e-4ed7-920e-71cb9ceba49f", "event": "photo_calculated_by_app", "idempotency_id": "5f8a3745-516f-46e0-b69c-26275abf8ff3", "image_id": "ef56960f-e690-4279-8d7b-3a3842cafcb2", "image_meta": { "image_source": "native" }, "images": { "original": { "signed_url": "https://..." }, "restored": { "signed_url": "https://..." } }, "re_result": { "care_group": { "basic_care": "Oily", "eye_care": "Dark circles", "special_concerns": [ "Acne" ] }, "products": { "cleanser": [ "4_2" ], "day_cream": [], "exfoliation": [], "eye_care": [ "12_12" ], "lotion": [ "4_6" ], "make_up_remover": [ "4_1" ], "night_cream": [ "4_4" ], "serum": [ "16_5" ], "spf": [ "4_7" ] }, "revision": "dev-298bb3b5" }, "subject_id": "eecbfb20-3336-4f11-bab2-cac6d1f5f850", "subject_meta": {}, "subject_name": "ivt9fwH3aTCUYXxPVPsqtk", "survey_answers": [ { "answer_id": "25fd7fc4-4a2a-46ee-b031-d75242cc516f", "answer_values": [ "1" ], "question_id": "8f9eb8dd-0c0a-4776-a3cc-291704645370", "question_text": "1" }, { "answer_id": "6bc782e5-696c-4bec-a768-edf91a1430d4", "answer_values": [ "02" ], "question_id": "a0fded87-389a-40fc-a6c2-9d79ffcb014c", "question_text": "2" }, { "answer_id": "58bd4c3d-2808-4834-8de2-1c14969227d8", "answer_values": [ "2", "3", "1" ], "question_id": "8bb18cd8-b933-4181-aca1-14c2baf3a14b", "question_text": "3" } ] } ```
### 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: ```bash curl -X POST {url} \ -H "{Authorization key}: Basic {Authorization value}" ``` 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: ```bash curl -X POST {url} \ -H "Authorization: Basic dXNlcm5hbWU6cGFzc3N3b3Jk" ``` 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: ```bash curl -X POST {url} \ -H "Authorization: Bearer {token}" ``` 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: ```bash curl -X POST {url} \ -H "Authorization: Bearer your_bearer_token" ``` 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 Consumer App If you want to receive answers for your survey from Consumer App (assuming your dataset was created for Consumer App and your Consumer 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 ```json { "survey_answers": [ { "answer_id": "ea3728f2-5ae9-45cf-bc08-98f229f06147", "answer_values": [ "User" ], "question_id": "9f5473fb-3330-4e70-b9b1-e832bdb983e2", "question_text": "Who are you?" } ] } ```
## 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)) ```json { "images": { "original": { "signed_url": "https://..." }, "restored": { "signed_url": "https://..." } }, "area_results": [ { "area_name": "face", "name": "Skin tone", "sub_metrics": [], "tech_name": "skintone_class", "value": "Intermediate", "widget_meta": null, "widget_type": "category" }, { "area_name": "face", "name": "Perceived Age", "sub_metrics": [], "tech_name": "perceived_age", "value": 20, "widget_meta": null, "widget_type": "numeric" }, { "area_name": "face", "name": "Eye Age", "sub_metrics": [], "tech_name": "eye_age", "value": 28, "widget_meta": null, "widget_type": "numeric" }, { "area_name": "left_eye_area", "name": "Left Eye Age", "sub_metrics": [], "tech_name": "left_eye_age", "value": 27, "widget_meta": null, "widget_type": "numeric" } ], "batch_id": "a06de0cc-fe24-4f05-bc9d-e2a9fe1f0ca6", "company_id": "2e393306-916c-4f6f-bfb5-211950a6b131", "dataset_id": "6020067e-ea7b-435e-9d16-a28128023f4e", "event": "photo_calculated_by_all_apps", "idempotency_id": "51123618-1ec6-4780-a410-f1875efeabe3", "image_id": "2d4679c1-ba5b-475a-a71a-d7e505689dad", "image_meta": {}, "re_result": { "care_group": { "basic_care": "Normal", "eye_care": "Dark circles", "special_concerns": [ "Vessels" ] }, "products": { "cleanser": [ "25_2" ], "day_cream": [ "25_3" ], "exfoliation": [], "eye_care": [ "12_12" ], "lotion": [ "1_6" ], "make_up_remover": [ "25_1" ], "night_cream": [ "25_4" ], "serum": [ "25_5" ], "spf": [ "1_7" ] }, "revision": "test-2a6a2c27" }, "subject_id": "02b2a283-3fb1-4778-805e-fa72db553882", "subject_meta": {}, "subject_name": "s4", "survey_answers": [] } ```
Merged webhook example (for the Product Recommendation System 2.0) ```json { "images": { "original": { "signed_url": "https://..." }, "restored": { "signed_url": "https://..." } }, "area_results": [ { "area_name": "face", "name": "Eye Age", "sub_metrics": [], "tech_name": "eye_age", "value": 21, "widget_meta": null, "widget_type": "numeric" }, { "area_name": "left_eye_area", "name": "Left Eye Age", "sub_metrics": [], "tech_name": "left_eye_age", "value": 21, "widget_meta": null, "widget_type": "numeric" }, { "area_name": "right_eye_area", "name": "Right Eye Age", "sub_metrics": [], "tech_name": "right_eye_age", "value": 21, "widget_meta": null, "widget_type": "numeric" } ], "batch_id": "1664e158-e6c8-41cd-9a88-a109dbf72679", "company_id": "23aeffeb-ce53-4611-80af-846daeba62f4", "dataset_id": "aaec4b5a-182c-413c-9677-f4ac62cf0f9f", "event": "photo_calculated_by_all_apps", "idempotency_id": "d22b7fe4-9ed9-4b6f-802e-ed032d797173", "image_id": "ac845fc0-720d-4563-a9ea-ae8ea58bf926", "image_meta": { "image_source": "native" }, "re_result": null, "recommendation_system_result": { "featured_products": { "cleanser": [], "exfoliator": [], "eye_care": [], "makeup_remover": [], "masks_patches": [], "moisturizer": [], "sunscreen": [], "toner": [], "treatment": [ { "active_ingredients": [], "cart_integration_id": "43287234969833", "compare_at_price": null, "concerns": [ "redness" ], "created_at": "2025-02-07T14:55:23.179976+00:00", "currency": "USD", "description": "Time for a soothing pick-me-up. This lightweight watery gel serum soothes the look of redness and irritation, and helps strengthen, balance, and improve skin\u2019s defences against dryness. Potent formula provides relief from the appearance of irritation. Skin appears soft, hydrated, and healthier-looking.Specially formulated with Niacinamide and Dr.Jart+'s Green Repair Solution\u2122 \u2014 a proprietary derma complex that brings together the reparative power of Tiger Grass (Centella Asiatica aka Cica), with a skin-boosting blend of herbs, minerals, a moisturising humectant, and a probiotic ferment \u2013 to soothe, calm, and moisturise the look of skin.Dermatologist tested.", "how_often_to_apply": null, "id": 75232, "image": "https://cdn.shopify.com/s/files/1/0648/6153/6489/products/dj_sku_H58101_1000x1000_0.jpg?v=1656420136", "is_featured": true, "link": "https://skinanalysis.pro/products/cicapair\u2122-tiger-grass-re-pair-serum", "name": "[Sample] Dr. Jart+ Cicapair\u2122 Tiger Grass Re.Pair Serum", "other": [], "price": "44.02", "priority": 1, "skin_type": [ "normal" ], "status": "active", "updated_at": "2025-02-09T22:28:02.874717+00:00", "vendor_code": "7767169269993", "when_to_apply": [ "pm", "am" ] } ] }, "recommended_products": { "cleanser": [], "exfoliator": [], "eye_care": [ { "active_ingredients": [], "cart_integration_id": "43286694265065", "compare_at_price": null, "concerns": [ "under_eye_lines" ], "created_at": "2025-02-07T14:55:22.890409+00:00", "currency": "USD", "description": "This soothing, fast-penetrating eye balm smoothes, reduces visible puffiness and de-stresses the look of the eyes for a calm, well-rested look.\n\nDeeply emollient, this ultra-luxe balm hydrates, conditions and visibly softens lines, wrinkles and other signs of fatigue.", "how_often_to_apply": null, "id": 75211, "image": "https://cdn.shopify.com/s/files/1/0648/6153/6489/products/LM_SKU_2NF301_26149_680x680_0.png?v=1656411023", "is_featured": false, "link": "https://skinanalysis.pro/products/the-eye-balm-intense", "name": "[Sample] La Mer The Eye Balm Intense", "other": [], "price": "200.00", "priority": 1, "skin_type": [ "combination", "normal", "dry", "oily" ], "status": "active", "updated_at": "2025-02-09T22:27:12.332006+00:00", "vendor_code": "7766933471465", "when_to_apply": [ "pm", "am" ] }, { "active_ingredients": [], "cart_integration_id": "43286665396457", "compare_at_price": null, "concerns": [ "under_eye_lines" ], "created_at": "2025-02-07T14:55:22.90248+00:00", "currency": "USD", "description": "Wrinkle Corrective Eye Contour Cream is a silky-soft cream that helps repair the appearance of lines and deep wrinkles on the eye contour as it visibly renews natural glow and restores suppleness. The eye contour is smoother, softer and radiant-looking. Formulated with 75% of ingredients from natural origin such as Magnolia and Algae extract.Free from parabens, mineral oil, phthalates, formaldehyde.\n\nSkincare benefits:\n\nReduces appearance of wrinklesProvides softer, smoother and comforted skinIlluminates the eye contourVisibly renews the eye contour's natural glow and restores supplenessIdeal For:\n\n\nReducing lines and wrinklesReducing dryness, dehydrationUsage:\nMorning and evening, apply Wrinkle Corrective Eye Contour Cream with the tips of your index fingers on the orbital bone around the eyes, starting from the inner corner of the eye. Let the cream penetrate by spreading it gently from the inside to the outside of the eye, following the curve of the bone. Do not apply the product directly below the lashes.", "how_often_to_apply": null, "id": 75212, "image": "https://cdn.shopify.com/s/files/1/0648/6153/6489/products/da_sku_D40R01_750x1000_0.jpg?v=1656410674", "is_featured": false, "link": "https://skinanalysis.pro/products/wrinkle-corrective-eye-contour-cream", "name": "[Sample] Darphin Wrinkle Corrective Eye Contour Cream", "other": [], "price": "77.47", "priority": 1, "skin_type": [ "combination", "normal", "dry", "oily" ], "status": "active", "updated_at": "2025-02-09T22:28:17.607813+00:00", "vendor_code": "7766921380073", "when_to_apply": [ "pm", "am" ] } ], "makeup_remover": [], "masks_patches": [], "moisturizer": [], "sunscreen": [], "toner": [], "treatment": [ { "active_ingredients": [], "cart_integration_id": "43287078535401", "compare_at_price": null, "concerns": [ "breakouts" ], "created_at": "2025-02-07T14:55:23.092778+00:00", "currency": "USD", "description": "Who It's For\n\nAll Skin Types\n\nWhat It Does\n\nGentle, hydrating formula with salicylic acid helps clear and treat acne without dryness. Potent anti-aging technology visibly improves lines, wrinkles, texture. See skin that\u2019s clearer, smoother, and more youthful-looking.\n\nKey Ingredients\n\n\nSalicylic acid helps rid skin of dirt and oil to reduce breakouts.\n\nWhey protein: Helps visibly smooth and re-plump skin.\n\nAcetyl glucosamine and clary sage extract: Help slough away pore-clogging dead skin cells.\n\nOur Clinique Clean PhilosophyNo parabens. No phthalates. No fragrance. Just happy skin.\n\nWhat else is this product free of?\nOil Free, Free of Denatured Alcohol, Free of Synthetic Colours, SLS Free, SLES Free, Sulfate Free.\n\nHow To Use\nAfter cleansing, apply 2-3 drops twice a day all over face, avoiding eye-area.", "how_often_to_apply": null, "id": 75226, "image": "https://cdn.shopify.com/s/files/1/0648/6153/6489/products/cl_sku_ZH0601_1200x1500_0.png?v=1656416472", "is_featured": false, "link": "https://skinanalysis.pro/products/acne-solutions\u2122-acne-line-correcting-serum", "name": "[Sample] Clinique Acne Solutions\u2122 Acne + Line Correcting Serum", "other": [], "price": "44.44", "priority": 1, "skin_type": [ "combination", "normal", "dry", "oily" ], "status": "active", "updated_at": "2025-02-09T22:26:42.289805+00:00", "vendor_code": "7767121985769", "when_to_apply": [ "pm", "am" ] } ] }, "user_tags": { "concerns": [ "breakouts", "redness", "under_eye_lines" ], "skin_type": "combination" } }, "subject_id": "2e835f90-2903-43bc-bedf-50e444c41724", "subject_meta": {}, "subject_name": "orUV4npExAT45KysrHontZ" } ```
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) ```json { "images": { "original": { "signed_url": "https://..." }, "restored": { "signed_url": "https://..." } }, "area_results": [ { "area_name": "face", "name": "Skin type", "sub_metrics": [ { "name": "U-zone skin type", "tech_name": "u_zone_skin_type_class", "value": "Oily", "widget_meta": null, "widget_type": "category" }, { "name": "T-zone skin type", "tech_name": "t_zone_skin_type_class", "value": "Oily", "widget_meta": null, "widget_type": "category" } ], "tech_name": "face_skin_type_class", "value": "Oily", "widget_meta": null, "widget_type": "category" }, { "area_name": "face", "name": "Hydration Score", "sub_metrics": [ { "name": "Hydration Level", "tech_name": "hydration_level", "value": "Normal Hydration", "widget_meta": null, "widget_type": "category" } ], "tech_name": "hydration_score", "value": 98, "widget_meta": null, "widget_type": "bad_good_line" }, { "area_name": "face", "name": "Pores Score", "sub_metrics": [ { "name": "Pores Number", "tech_name": "pores_number", "value": 22, "widget_meta": null, "widget_type": "numeric" }, { "name": "Pores Density", "tech_name": "pores_density", "value": 0, "widget_meta": null, "widget_type": "density" } ], "tech_name": "Pores_score", "value": 99, "widget_meta": null, "widget_type": "bad_good_line" } ], "batch_id": "a35a207c-172a-4a36-8186-d77ec9bd132b", "company_id": "2e393306-916c-4f6f-bfb5-211950a6b131", "dataset_id": "6020067e-ea7b-435e-9d16-a28128023f4e", "event": "photo_calculated_by_all_apps_timeout", "idempotency_id": "24f20bba-60ea-42f4-a453-049077cc8853", "image_id": "13679cc8-0527-4114-8399-21411fc815b6", "image_meta": {}, "re_result": null, "subject_id": "ee05d314-ec6f-4158-a0c5-a99157e1ab33", "subject_meta": {}, "subject_name": "s13", "survey_answers": [] } ```
*** {% hint style="warning" %} Not a Haut.AI client yet? {% endhint %} Book a demo Platform overview on haut.ai --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.saas.haut.ai/haut.ai/developers/saas-api-overview/api-for-webhooks.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.