DELETEMethod DELETE/partner/webhooks/{webhook_id}

You permanently delete a notification subscription of your brand. When you leave this page, you will know how to build the call, including the mandatory confirmation, and you will know what the deletion destroys along with the subscription.

Full address:

DELETE https://api.sealtrust.io/v1/partner/webhooks/{webhook_id}?confirm={url}

The same endpoint also answers without the /v1 prefix, at https://api.sealtrust.io/partner/webhooks/{webhook_id}. Both addresses call the same code. Use the /v1 form for a new integration.

#Authorization

API key in the Authorization header, in the Bearer format.

The deletion itself requires the webhooks:write scope. Reading the URL beforehand, needed to build the confirmation, additionally requires the webhooks:read scope. In practice, the key that runs this sequence carries both scopes. A key that does not carry the required scope receives a 403 whose message names the missing scope.

A subscription is only visible and deletable by a key of the brand it belongs to. A subscription number that belongs to another brand answers 404, like a number that does not exist. The response never says whether the subscription exists elsewhere.

This deletion stays open whatever your plan. If your plan no longer includes notifications, you can still delete the subscriptions recorded in your name. It is creation and modification that require the plan to include notifications.

#Mandatory confirmation

On top of the scopes, the call requires a confirmation. The server compares the value of the confirm query parameter with the URL it has stored for that subscription number. Three cases.

The comparison tolerates case, leading and trailing spaces, and equivalent Unicode forms. It tolerates nothing else. One punctuation character too many or one missing URL segment gives a CONFIRMATION_MISMATCH.

The error message never returns the expected URL to you. Read it with GET /v1/partner/webhooks/{webhook_id} or in the list returned by GET /v1/partner/webhooks, url field. Both of these reads require the webhooks:read scope.

#Rate limit

The rate is measured over a fixed window of 60 seconds. We first apply the value set on your brand, if we have set one. Otherwise the one of your plan. In the absence of both, the fallback value is 120 calls per window.

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

The response carries two sets of X-RateLimit-* headers, and both sets carry the same header names. Keep the values of the set that comes with X-RateLimit-Scope: that is the one describing the limit of your key or the one of your brand. The second set comes from a per-IP-address counter and does not describe the budget of your key. Read the complete list of the headers of the response before trusting a value.

The set that carries X-RateLimit-Scope is present on the 204 response and on the error responses that come after the rate check.

A refusal returns 429 with Retry-After, expressed in seconds remaining in the current window. That value is never lower than 1.

#Path and query parameters

#Headers

#Request body

This endpoint has no request body. All the information you send fits in the subscription number and in the confirm parameter.

#Example request

Deletion of subscription number 7, whose registered URL is https://exemple-sas.test/sealtrust/evenements. The three examples do the same thing: they read the subscription, then they delete it by sending its URL back. The key used carries both the webhooks:read and webhooks:write scopes, the read of the first step requiring the former and the deletion of the second requiring the latter.

# 1. Read the subscription to learn its registered URL.
curl -i https://api.sealtrust.io/v1/partner/webhooks/7 \
  -H "Authorization: Bearer st_test_0000000000000000000000000000000000000000000000"

# 2. Delete by sending that URL back in confirm.
curl -i -X DELETE \
  "https://api.sealtrust.io/v1/partner/webhooks/7?confirm=https://exemple-sas.test/sealtrust/evenements" \
  -H "Authorization: Bearer st_test_0000000000000000000000000000000000000000000000"

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

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

// 1. Read the subscription to learn its registered URL.
const abonnement = await sealtrust.webhooks.get(7);
console.log(abonnement.url); // https://exemple-sas.test/sealtrust/evenements

// 2. Delete by sending that URL back.
await sealtrust.webhooks.delete(abonnement.id, abonnement.url);

import requests

entetes = {
    "Authorization": "Bearer st_test_0000000000000000000000000000000000000000000000",
}

# 1. Read the subscription to learn its registered URL.
lecture = requests.get(
    "https://api.sealtrust.io/v1/partner/webhooks/7",
    headers=entetes,
    timeout=30,
)
lecture.raise_for_status()
adresse = lecture.json()["url"]
print(adresse)  # https://exemple-sas.test/sealtrust/evenements

# 2. Delete by sending that URL back.
suppression = requests.delete(
    "https://api.sealtrust.io/v1/partner/webhooks/7",
    headers=entetes,
    params={"confirm": adresse},
    timeout=30,
)

print(suppression.status_code)  # 204

The confirm parameter travels in the URL of the request. If your tool does not do it for you, percent-encode its value before writing it.

#Example response

HTTP status code 204. The body is empty.

HTTP/1.1 204 No Content
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118
X-RateLimit-Reset: 1755676800
X-RateLimit-Scope: key
x-ratelimit-limit: 600
x-ratelimit-remaining: 597
x-ratelimit-reset: 1755676800
x-request-id: 00000000000000000000000000000000

The first four headers describe the limit of your key or of your brand. The next three come from the per-IP-address counter. x-request-id identifies the call in our logs and comes with every response.

After that 204, the subscription no longer appears in GET /v1/partner/webhooks, and GET /v1/partner/webhooks/{webhook_id} answers 404 for that number. Events are no longer delivered to that URL.

#Errors

The body of an error response carries a detail field. On the two confirmation refusals, that field is an object containing code, message and what_to_type. In the other cases, it contains a sentence or a list.

Example body of a confirmation refusal, HTTP status code 400:

{
  "detail": {
    "code": "CONFIRMATION_MISMATCH",
    "message": "What you typed is not the subscription's url. Nothing was changed. This endpoint stops receiving events and its signing secret is destroyed. A new subscription for the same url gets a different secret, so the receiver must be reconfigured. Read the url from GET /partner/webhooks/{id}.",
    "what_to_type": "the subscription's url"
  }
}

That message is returned as is by the service, in English. On the secret, the sentence to remember is the one in the callout at the top of the page: the secret of a new subscription is the one you choose.

A deletion already carried out returns 404 on the second call. This endpoint is therefore not replayable: treat the 404 as the confirmation that the subscription no longer exists.

#See also

• GET /partner/webhooks/{webhook_id}, read a subscription and its delivery state.
• PUT /partner/webhooks/{webhook_id}, change the URL, the events or the secret of a subscription.
• GET /partner/webhooks, list your notification subscriptions, page by page.
• Receive events by webhook, create a subscription, check a signature, catch up on lost events.