POSTMethod POST/partner/webhooks

You register an HTTPS address that will receive the events of your brand, and you choose the event types sent to that address. The subscription belongs to the brand of the key that calls, or, with a reseller key, to the client brand named by brand_code. By the end of this page, you will know which event types actually go out today, how to verify the signature of a delivery, and which response your integration receives at every refusal.

Full address:

POST https://api.sealtrust.io/v1/partner/webhooks

The same endpoint also answers without the /v1 prefix, at https://api.sealtrust.io/partner/webhooks. The two addresses call the same code and both are permanent. Use the /v1 form for a new integration.

#Authorization

API key in the Authorization header, in the Bearer format followed by a space then the key.

The Prestige, Maison and Inside plans carry webhook notifications. The Essentiel plan does not carry them, and neither does the trial account. If your plan does not carry them, you receive a 403 on this route.

The subscription's brand is the key's. With a reseller key, brand_code names one of your client brands. Another brand, or a code that names no brand, is refused with 403 and nothing is created. It is the plan of the subscription's brand that must include notifications. A subscription created for a client brand is sent only while your reseller contract exists and the brand is still your client, retries included.

A missing scope returns 403 without creating anything.

#Rate limit

We measure the rate over a fixed 60-second window. The cap depends on your plan, and we can raise it for your brand without changing your subscription. Read the current value in the X-RateLimit-Limit header of every accepted response. When no value is set on your brand or on your plan, the fallback value is 120 calls per window.

Two counters are layered, with the same cap: one per key, one for the sum of all the keys of your brand. Creating one more key therefore does not increase the total rate allowed.

Exceeding it returns 429 with these four headers, plus Retry-After. Retry-After counts the seconds that remain in the current window, and is at minimum 1.

#Path and query parameters

None. This endpoint reads neither path parameter, nor query parameter. Everything is in the body.

#Request body

Content-Type application/json.

The body accepts only these three names. Any other field makes the request fail with a 422.

#The 17 accepted event types

They are exactly the types we deliver today. A name absent from this list makes the request fail with a 422.

Life cycle of an item

product.minted, product.transferred, transfer.accepted

Scans and security

product.scanned, product.gray_market, clone.alert

Returns and warranty

return.requested, return.received, return.completed, return.rejected, return.expired, warranty.claimed

Buyback

buyback.offered, buyback.accepted, buyback.declined, buyback.completed, buyback.expired

#What is accepted is what is sent

Since 12 September 2026 the list of types accepted for a subscription is exactly the list of types the product emits. Six names used to be accepted without anything sending them: product.burned, product.status_changed, batch.completed, batch.failed, warranty.expiring_soon and certificate.issued. They are now refused at creation.

A subscription created before this change and carrying one of those names stays in place and receives nothing, as before.

#What the secret does

Every delivery carries the header X-Webhook-Signature, in the format t=<horodatage>,v1=<empreinte>. The hash is an HMAC-SHA256 computed with your secret over the string made of the timestamp, a dot, then the body received byte for byte. Verify the signature on the raw bytes you receive, before decoding the JSON.

Three other headers come with every delivery.

X-Webhook-Event tells you which event it is when a subscription covers several types. It stays outside the signature, so it authenticates nothing. When your receiver must route on an authenticated value, register one address per event type, and use this header only to read your logs.

A subscription always has a secret, and we refuse to send a delivery that would not be signed. Without a secret in the request, we generate one of 43 characters.

#Example request

The three programs do the same thing: they register one address for two event types that are actually delivered, with a signing secret.

curl -X POST https://api.sealtrust.io/v1/partner/webhooks \
  -H "Authorization: Bearer st_live_0000000000000000000000000000000000000000000000" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example-sas.example.com/sealtrust/evenements",
    "events": ["product.scanned", "clone.alert"],
    "secret": "secret-partage-de-demonstration-a-remplacer"
  }'

import { SealTrustClient } from "@sealtrust-io/sdk";

const sealtrust = new SealTrustClient({
  apiKey: "st_live_0000000000000000000000000000000000000000000000",
});

const abonnement = await sealtrust.webhooks.create({
  url: "https://example-sas.example.com/sealtrust/evenements",
  events: ["product.scanned", "clone.alert"],
  secret: "secret-partage-de-demonstration-a-remplacer",
});

console.log(abonnement.id, abonnement.health);

import requests

response = requests.post(
    "https://api.sealtrust.io/v1/partner/webhooks",
    headers={
        "Authorization": "Bearer st_live_0000000000000000000000000000000000000000000000",
        "Content-Type": "application/json",
    },
    json={
        "url": "https://example-sas.example.com/sealtrust/evenements",
        "events": ["product.scanned", "clone.alert"],
        "secret": "secret-partage-de-demonstration-a-remplacer",
    },
    timeout=30,
)

response.raise_for_status()
abonnement = response.json()
print(abonnement["id"], abonnement["health"])

#Example response

A successful creation answers 201 Created.

{
  "id": 41,
  "brand_code": "7K3QXW9M2A",
  "brand_id": 12,
  "url": "https://example-sas.example.com/sealtrust/evenements",
  "events": ["product.scanned", "clone.alert"],
  "is_active": true,
  "health": "healthy",
  "created_at": "2026-08-20T09:14:03.512841+00:00",
  "updated_at": "2026-08-20T09:14:03.512841+00:00"
}

#Errors

The body of an error response contains a single field, detail.

#See also

• GET /partner/webhooks, list your notification subscriptions, page by page.
• GET /partner/webhooks/{webhook_id}, read a subscription and its delivery state.
• PUT /partner/webhooks/{webhook_id}, modify the address, the events or the secret of a subscription.
• DELETE /partner/webhooks/{webhook_id}, delete a subscription and the signing secret attached to it.
• Receiving events by webhook, create a subscription, verify a signature, catch up on the events that were lost.