🟢API for Webhooks

This page describe how to manage Webhooks via API>

Webhooks are automated notifications sent from one platform to another when a specific event occurs.

You can also read about webhooks here.

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
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
201Success
application/json
post
POST /api/v1/companies/{company_id}/datasets/{dataset_id}/webhooks/ HTTP/1.1
Host: saas.haut.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 188

{
  "url": "https://example.com",
  "authorization": "query",
  "authorization_key": "text",
  "authorization_value": "text",
  "method": "post",
  "enabled": true,
  "add_survey_answers": true,
  "merge_webhooks": true
}
{
  "url": "https://example.com",
  "authorization": "query",
  "authorization_key": "text",
  "authorization_value": "text",
  "method": "post",
  "enabled": true,
  "secret_key": "text",
  "add_survey_answers": true,
  "merge_webhooks": true
}

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.

    {
        "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
{
    "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
{
    "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:

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:

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:

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:

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 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
{
  "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 (legacy))
{
    "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)
{
    "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",
                        "sensitive",
                        "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",
                        "sensitive",
                        "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",
                        "sensitive",
                        "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)
{
    "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": []
}

Last updated

Was this helpful?