What developer tools does Looksy provide?
Looksy provides a server-to-server try-on endpoint authenticated with a per-store API key and an outbound webhook for completed storefront product try-ons recorded by Looksy’s event pipeline. Both are configured under Looksy → Settings → Developer tools. API generations use the same product configuration, plan usage, and billing-period safety limit as storefront generations.
Generate or revoke the API key and connect the signed webhook from Developer tools. This example uses a Looksy test store with no key or webhook connected.
Generate an API key
- Open Settings → Developer tools.
- Under Try-on API, select Generate key.
- Copy the key immediately and store it as a secret.
Send a try-on request
SendPOST https://withlooksy.gadget.app/v1/try-on with JSON and the API key as a Bearer token.
A successful response includes
success, the generated image, and the resolved product and variant IDs. A rate-limited response uses HTTP 429 and includes Retry-After.
Common error codes include MISSING_OR_INVALID_KEY, INVALID_BODY, INVALID_PRODUCT, INVALID_VARIANT, MISSING_IMAGE, UNSUPPORTED_IMAGE_TYPE, INVALID_IMAGE, REQUEST_TOO_LARGE, RATE_LIMITED, and INTERNAL_ERROR. Generation and account checks can return other bounded error codes; handle non-success responses without assuming an image is present.
Connect a webhook
Under Developer tools → Webhooks, enter a public HTTPS endpoint. Looksy requires HTTPS, rejects credential-bearing URLs, and blocks common literal local or private hostnames. Use an endpoint that is publicly routable and protected by the signature check below. Copy the signing secret when it appears. Connecting a different endpoint rotates that secret. Looksy currently sends:product_tried_onwhen Looksy records a successful storefronttry_on_successevent for a product.
POST /v1/try-on do not emit this storefront webhook. If your integration needs to track its own API requests, record the API response in your system rather than waiting for product_tried_on.
Every request includes:
The JSON payload can include the shop domain, product and variant IDs and titles, a hashed anonymous visitor identity, a logged-in Shopify customer ID when known, occurrence time, and event ID. Treat nullable fields as optional context rather than delivery guarantees.
Verify the signature
Compute HMAC-SHA256 over the exact raw request bytes using the signing secret. Compare the completesha256=<hex> value with a constant-time comparison before parsing or acting on the event.
eventId for idempotency because webhook deliveries may be retried.
Delivery and retry behavior
Webhook delivery is best-effort. Looksy retries network failures and HTTP408, 429, or 5xx responses up to three times after the initial attempt, using exponential backoff. Other non-success responses are not retried. After the final failed attempt, the delivery is dropped.
Return a 2xx response only after the event has been safely accepted. Keep webhook processing fast and move slow work to your own queue.
Test API and webhook handling without real shopper data. Do not send API keys, webhook secrets, or shopper images to Looksy support.