Webhooks Overview & Event Types

You register an HTTPS callback and JOOR posts a signed notification when something you can see changes. Each notification embeds the complete current data for whatever changed, so your handler applies it and moves on.

Onboarding (once)              Steady state (forever)
--------------------------     -------------------------------------------
1. create subscription         POST to your callback
2. POST .../test                -> verify HMAC, return 200 fast
3. seed with the bulk export    -> enqueue internally, apply from your queue
                                Daily: re walk connections and collections

Event types

Event	What it asserts	Typical causes
`product.created`	It entered your catalog	A new product; a collection shared with you; a price type granted; a brand connected
`product.updated`	Content changed while in your catalog	Core fields, SKUs, prices, images, collection membership, categories, badges, tags, materials, delivery windows
`product.deleted`	It left your catalog	The product is no longer visible to you; a collection unshared; a price type revoked; a brand disconnected; the product lost the last price you can see

None of these is a statement about JOOR's database. They are statements about your catalog. The same edit at a brand is a created for one retailer, an updated for another, and nothing at all for a third.

Two consequences worth designing for:

product.deleted means remove, not purge. The product is no longer yours to sell. It may come back later as a fresh product.created, with every section re embedded. Keep whatever internal record makes that cheap.
product.created is opt in. List it in events or you will never receive it. An existing subscription is never upgraded silently, so a handler with else: raise will not start failing because we shipped a new event.

Ordering. The only ordering guarantee on this page is that a deletion is never preceded by a spurious update: if a product is edited and then leaves your catalog inside one window, you receive only the product.deleted. Beyond that, do not assume notifications for one product arrive in the order the edits happened. That is what version_at and the tie rule in "the apply rule" are for, covered on Delivery, Idempotency & Suspension.

The pages that follow cover, in order: Managing Subscriptions (create a subscription and manage it), Verifying Signatures (prove a request really came from JOOR), The Payload Contract & Worked Examples (what is inside a notification), Delivery, Idempotency & Suspension (retries, failure handling, how to write a safe handler), and Coverage (what is and is not covered).