Register a partner webhook endpoint

Register a destination for the events of all your vendors and get back its signing
secret. The secret is shown once. If it is lost, rotate it.

The URL must be HTTPS and resolve to a publicly reachable address. alias is unique
among your endpoints, and a scan that names it (the webhook parameter on
POST /skin/analyze) is delivered there when the vendor has no endpoint of its own
with that alias.

Deliveries are signed per attempt exactly like a vendor's, and a delivery to a
partner endpoint has the same body plus vendor: {id, slug}.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params
string
required
length ≤ 64
^[a-zA-Z0-9][a-zA-Z0-9_-]*$
uri
required
length ≤ 2048
string | null
events
array of objects
required
length ≥ 1
events*
Allowed:

scan.completed fires once a scan has finished analysing. Face and body arrive as a
single event: a body add-on belongs to the same scan and does not fire its own.

recommendation.ready fires once that scan's product routine has finished generating.
It can arrive well after scan.completed for the same batch.

procedure.ready fires once that scan's in-clinic treatment suggestions have
finished generating. It is INDEPENDENT of recommendation.ready: products and
treatments generate on separate queues and either can land first, so do not wait
for one before handling the other, and do not read the absence of one as a
statement about the other. A scan may produce only one of them, depending on
which recommendation types the vendor has enabled.

wheel.reward_won fires once a shopper's Spin the Wheel outcome is saved with a
reward. The event carries the code and its terms; the Oyster Shopify app,
WooCommerce plugin, or a store registered through
POST /integrations/storefront/wheel/capabilities creates the code in its checkout. data holds reward_id,
code, email, type (percentage_discount, fixed_discount, free_item,
free_delivery, free_scan), value, currency, min_order_amount,
usage_limit, expires_at, instructions, restrictions
(allowed_product_ids, excluded_product_ids, combines_with_discounts),
product_id and variant_id for a free item, terms_hash, vendor_id and
redemption_authority, the checkout the reward was issued for (oyster,
shopify, woocommerce, or store for a registered store), which already honours
it. Product ids are that checkout's own. A store reward also carries sku and
restrictions.allowed_skus / restrictions.excluded_skus. Every other receiver decides what to do with the reward: show it,
email it, or honour it in a checkout of its own, but not in one the named checkout
already covers, or the code works in both and Oyster only counts redemptions at
the named one. A store that has neither an app nor a registration receives every
reward as oyster. The code is live as soon as the event is sent; a store that cannot
honour it simply lets it go unused.

scan.completed also carries a customer object with whatever the widget was
configured to collect: email, first_name, last_name and phone_number, each
present only when it was actually collected. It is an empty object for a vendor who
collects nothing, whose customers are identified by external_user_ref alone. The
same object is written into result.json, so a consumer that treats the webhook as
a trigger and reads everything from its own bucket does not lose it.

booking.paid fires once per paid booking, whoever collected the payment. Its data
is a BookingPaidEventData. A free booking, or one paid offline at the clinic, sends
nothing. Partners receive it for every vendor they manage and can run vendor payouts
from it as well as from GET /partner/settlements.

For a vendor who keeps their own scan data, these events carry a storage block
naming objects written into that vendor's own bucket, and the recommendations
arrive as their own files in the same prefix: scan.completed names the captures
and result.json, recommendation.ready names recommendations.json, and
procedure.ready names procedures.json. The analysis is handed over as soon as
it exists rather than waiting on generation, so a consumer that only reads
scan.completed still receives a complete scan. A phase the vendor has switched
off produces no file and no event.

Responses

403

Missing the permission or scope.

422

Validation failed, the alias is taken, or the URL is not publicly reachable.

Language
Credentials
Bearer
JWT
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json