Event types

Coming

Each event below says when it fires and lists the fields in its data. In the console, pick the events each endpoint listens for; each event says whether a new endpoint starts with it picked.

A tag beside an event's name is its intended recipient: the person Diamra notifies about it, the owner or the customer. Your endpoint gets every event it listens for, whoever the recipient is. Each body's recipient names the one for that delivery: whom Diamra notifies about it, whether or not your store has switched that email off, so a server that sends its own notifications knows whom to tell. An event with no tag notifies nobody, and its recipient is null. message.created has both tags; its recipientis whichever side didn't write the message.

Diamra may add event types, and fields to a type, so ignore any you don't recognize and still answer with a 2xx. An endpoint set to every event also gets the types added later. Once webhooks open, the names and fields on this page will stay as they are.

customer is the same object as on the studio's messages: idis Diamra's id for the customer, the same on every device, and phone is in international format, such as +15551234567. Picture links are public WebP images, 1024 pixels square, and need no sign-in. The words in from are listed under Where each detail came from.

Webhooks come from Diamra's servers, so they report what the servers know. Something that happens only on the customer's screen, such as the studio resizing or a price being displayed, has no webhook; only the studio's messages report it. The table at the end of this page matches each studio message to its webhook, where there is one.

Projects

project.started

owner

A customer starts a project, or your team starts one on your bench. A new endpoint starts with it picked.

Field	What it holds
project_id	Diamra's id for the project, the same as on the studio's messages. bench_url and salon_url use design_image_id instead.
design_image_id	The id of the design the project is for. It is the id in bench_url and salon_url.
design_id	Diamra's id for the set the design came from, as in design.generated.
image_url	A link to the design.
started_by	customer when the customer started it, owner when your team started it on your bench.
embed_origin	The page that framed the studio when the project started, as the browser reported it. Some browsers send only the site's address. null outside an embed.
customer	The customer: id (Diamra's id for them), email, phone, first_name and name. Anything Diamra doesn't know is null.
bench_url	Opens the project on your bench. It needs a bench sign-in.
salon_url	Opens the project for the customer: on your store, or on your website when the project started in an embed.

project.measurements_ready

customer

Measurements are shared with the customer. A new endpoint starts with it picked.

Field	What it holds
project_id	Diamra's id for the project, the same as on the studio's messages. bench_url and salon_url use design_image_id instead.
design_image_id	The id of the design the project is for. It is the id in bench_url and salon_url.
customer	The customer: id (Diamra's id for them), email, phone, first_name and name. Anything Diamra doesn't know is null.
salon_url	Opens the project for the customer: on your store, or on your website when the project started in an embed.

project.model_ready

customer

A 3D model is shared with the customer. A new endpoint starts with it picked.

Field	What it holds
project_id	Diamra's id for the project, the same as on the studio's messages. bench_url and salon_url use design_image_id instead.
design_image_id	The id of the design the project is for. It is the id in bench_url and salon_url.
customer	The customer: id (Diamra's id for them), email, phone, first_name and name. Anything Diamra doesn't know is null.
salon_url	Opens the project for the customer: on your store, or on your website when the project started in an embed.

project.video_ready

customer

A video of the piece is shared with the customer. A new endpoint starts with it picked.

Field	What it holds
project_id	Diamra's id for the project, the same as on the studio's messages. bench_url and salon_url use design_image_id instead.
design_image_id	The id of the design the project is for. It is the id in bench_url and salon_url.
customer	The customer: id (Diamra's id for them), email, phone, first_name and name. Anything Diamra doesn't know is null.
salon_url	Opens the project for the customer: on your store, or on your website when the project started in an embed.

project.crafting_photo_added

customer

A new photo of the piece in progress is shared. A new endpoint starts with it picked.

Field	What it holds
project_id	Diamra's id for the project, the same as on the studio's messages. bench_url and salon_url use design_image_id instead.
design_image_id	The id of the design the project is for. It is the id in bench_url and salon_url.
customer	The customer: id (Diamra's id for them), email, phone, first_name and name. Anything Diamra doesn't know is null.
salon_url	Opens the project for the customer: on your store, or on your website when the project started in an embed.
image_url	A link to the new photo of the piece.

project.delivery_updated

customer

Delivery details are saved. A new endpoint starts with it picked.

Field	What it holds
project_id	Diamra's id for the project, the same as on the studio's messages. bench_url and salon_url use design_image_id instead.
design_image_id	The id of the design the project is for. It is the id in bench_url and salon_url.
customer	The customer: id (Diamra's id for them), email, phone, first_name and name. Anything Diamra doesn't know is null.
salon_url	Opens the project for the customer: on your store, or on your website when the project started in an embed.

project.completed

customer

The project is marked complete. A new endpoint starts with it picked.

Field	What it holds
project_id	Diamra's id for the project, the same as on the studio's messages. bench_url and salon_url use design_image_id instead.
design_image_id	The id of the design the project is for. It is the id in bench_url and salon_url.
customer	The customer: id (Diamra's id for them), email, phone, first_name and name. Anything Diamra doesn't know is null.
salon_url	Opens the project for the customer: on your store, or on your website when the project started in an embed.

Estimates

estimate.generated

owner

An estimate finishes with a price the customer can see. A new endpoint starts with it picked.

Field	What it holds
project_id	Diamra's id for the project, the same as on the studio's messages. bench_url and salon_url use design_image_id instead.
design_image_id	The id of the design the project is for. It is the id in bench_url and salon_url.
estimate_id	Diamra's id for the quote.
price	The price with your markup, as a plain number such as 2450. currency names its currency.
currency	The price's three-letter currency code, such as USD.
confidence	How sure the estimate is, as a whole number from 0 to 100. The lower it is, the more the price can still change. It is null when the price is final.
image_url	A link to the design being priced.
piece_type	What the piece is, such as ring, earrings or pendant.
style	Its style, such as halo_ring or stud_earrings.
setting	How the stones are set, such as prong or bezel. The center stone's setting when there is one.
metal	The metal the price is for, named as on the estimate, such as 14K Gold or Platinum.
metal_color	The gold's color, such as yellow, white or rose. null for other metals.
metal_options	The other metals listed under the price, each as { metal, price } in the same currency.
center_stone	The main stone, with type (such as diamond), shape, carat_weight for one stone, count (2 for a pair of studs) and origin. origin is lab_grown or natural, as priced. For a stone the customer brings, origin is lab_grown when the stone was described as lab-grown, and null otherwise. origin is also null for other gems, such as a sapphire. center_stone itself is null when there is no center stone.
total_carat_weight	The carats of every stone, added up.
ring_size	The US ring size, on rings only.
from	Where each detail above came from, one word per detail, under the same names. The words are listed on the "Messages from the studio" page, under "Where each detail came from".
customer	The customer: id (Diamra's id for them), email, phone, first_name and name. Anything Diamra doesn't know is null.
salon_url	Opens the project for the customer: on your store, or on your website when the project started in an embed.

estimate.accepted

owner

The customer accepts a price. A new endpoint starts with it picked.

Field	What it holds
project_id	Diamra's id for the project, the same as on the studio's messages. bench_url and salon_url use design_image_id instead.
design_image_id	The id of the design the project is for. It is the id in bench_url and salon_url.
estimate_id	The quote the customer accepted.
price	The amount the customer said yes to, with your markup, as a plain number. currency names its currency.
currency	The price's three-letter currency code, such as USD.
piece_type	What the piece is, such as ring, earrings or pendant.
style	Its style, such as halo_ring or stud_earrings.
setting	How the stones are set, such as prong or bezel. The center stone's setting when there is one.
metal	The metal the customer said yes to, named as on the estimate.
metal_color	The gold's color, such as yellow, white or rose. null for other metals.
metal_options	The other metals listed under the price, each as { metal, price } in the same currency.
center_stone	The main stone, with type (such as diamond), shape, carat_weight for one stone, count (2 for a pair of studs) and origin. origin is lab_grown or natural, as priced. For a stone the customer brings, origin is lab_grown when the stone was described as lab-grown, and null otherwise. origin is also null for other gems, such as a sapphire. center_stone itself is null when there is no center stone.
total_carat_weight	The carats of every stone, added up.
ring_size	The US ring size, on rings only.
from	Where each detail above came from, one word per detail, under the same names. The words are listed on the "Messages from the studio" page, under "Where each detail came from".
customer	The customer: id (Diamra's id for them), email, phone, first_name and name. Anything Diamra doesn't know is null.
bench_url	Opens the project on your bench. It needs a bench sign-in.
image_url	A link to the accepted design.

Messages

message.created

customerowner

A customer or your team sends a message in a store thread. A new endpoint starts with it picked.

Field	What it holds
message_id	Diamra's id for the message.
conversation_id	The thread the message belongs to.
project_id	The project the thread is about, or null when the thread isn't about a project.
design_image_id	The id of that project's design, or null when the thread isn't about a project.
sender	Who wrote it: customer, or owner for your team.
text	The message, up to its first 600 characters.
customer	The customer: id (Diamra's id for them), email, phone, first_name and name. Anything Diamra doesn't know is null.

Customers

customer.access_requested

owner

A customer asks for access to your store. A new endpoint starts with it picked.

Field	What it holds
customer	The customer: id (Diamra's id for them), email, phone, first_name and name. Anything Diamra doesn't know is null.
requested_at	When the customer asked, as an ISO 8601 time in UTC.
embed_url	The page that framed the studio when they asked, as the browser reported it. Some browsers send only the site's address. null outside an embed.

customer.access_approved

customer

Your team approves a customer who asked for access, the first time. A new endpoint starts with it picked.

Field	What it holds
customer	The customer: id (Diamra's id for them), email, phone, first_name and name. Anything Diamra doesn't know is null.
approved_at	When your team approved them, as an ISO 8601 time in UTC.

Designs

design.generated

A set of designs finishes generating. This one fires often. A new endpoint starts without it.

Field	What it holds
design_id	Diamra's id for the set of designs.
image_count	How many designs came back, usually four.
image_urls	A link to each design in the set, in order.
customer	The customer: id (Diamra's id for them), email, phone, first_name and name. Anything Diamra doesn't know is null.

Studio messages and their webhooks

The table lists each message the embedded studio sends your page and the webhook your server can use instead, if there is one. A webhook fires wherever the event happens, on your website or on your store. A message reaches your page only while the studio is open on it. Where both exist, the webhook's data uses the message's field names.

Message	Webhook
diamra:ready	None. It reports the studio loading on your page.
diamra:navigate	None. It reports a view change inside the studio.
diamra:resize	None. It reports the studio's height on your page.
diamra:design.generated	`design.generated`
diamra:project.started	`project.started`
diamra:estimate.displayed	`estimate.generated`. It fires once per estimate, when the price is ready for the customer, not each time the studio shows it.
diamra:estimate.accepted	`estimate.accepted`
diamra:customer.signed_out	None. It answers your page's diamra:sign_out command.
diamra:navigated	None. It reports the studio moving between a group's page and one of its stores.

The envelope

Every body has the same envelope: the event's id (the same as webhook-id), its type, its recipient (customer, owner or null, as above), created_at (when it happened), your store, and datawith the event's fields in snake_case.

Body, shortenedJSON

{
  "id": "7b9e2f1c-3a44-4d2e-9f0b-0c1a2b3c4d5e",
  "type": "estimate.accepted",
  "recipient": "owner",
  "created_at": "2026-10-31T18:04:12Z",
  "store": { "id": "a1b2c3d4-...", "subdomain": "yourstore" },
  "data": {
    "project_id": "...",
    "design_image_id": "...",
    "estimate_id": "...",
    "price": 2450,
    "currency": "USD",
    "metal": "18K Gold",
    "customer": { "id": "...", "email": "jane@example.com", "phone": "+15551234567", "first_name": "Jane", "name": "Jane Doe" },
    "bench_url": "https://yourstore.diamra.com/bench/projects/<design_image_id>",
    "image_url": "https://.../design.webp"
  }
}