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. 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 key decides the brand. You cannot create a subscription for a brand other than its own, and no field of the body allows changing it.

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 23 accepted event types

A name absent from these two lists makes the request fail with a 422.

#The 17 types we deliver today

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

#The 6 types accepted at subscription and never emitted

product.burned, product.status_changed, batch.completed, batch.failed, certificate.issued, warranty.expiring_soon

These six names pass input validation and are recorded in your subscription. No code in the product emits them to this day, so your address will never receive a delivery carrying one of these names. Build no alert and no automation on them. We will update this list the day one of them goes out.

#What the secret does

When you supply a secret, 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.

Without a secret, the X-Webhook-Signature header is absent from your deliveries.

#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_test_0000000000000000000000000000000000000000000000" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://exemple-sas.example.com/sealtrust/evenements",
    "events": ["product.scanned", "clone.alert"],
    "secret": "secret-partage-a-remplacer"
  }'

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

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

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

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

import requests

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

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

#Example response

A successful creation answers 201 Created.

{
  "id": 41,
  "brand_id": 12,
  "url": "https://exemple-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.