---
title: "Subscribe to events"
method: POST
path: "/webhooks/subscriptions"
tags: ["Webhooks"]
---

# Subscribe to events

`POST /webhooks/subscriptions`

## Request

- Base URL: `https://services.certseal.com/api/v1`
- URL: `https://services.certseal.com/api/v1/webhooks/subscriptions`
- Auth: HTTP bearer

Register a URL to receive POSTs when the specified events fire
in this workspace. The response includes a one-time
`signingSecret` — store it immediately, you cannot recover it
later. URL constraints:

- Must be `https://` in production.
- Must not resolve to a loopback, link-local, or RFC1918
  address (re-checked after DNS at every delivery to defeat
  rebind attacks).
- Max 20 subscriptions per workspace.

## Request body

- WebhookSubscriptionInput
  - `url` string, uri, required: Endpoint that receives webhook POSTs. Must be `https://` in production and must not resolve to a private/loopback address.
  - `events` WebhookEventType[], required

## Response `201`

Subscription created. `signingSecret` is shown ONCE.

- object
  - `subscription` WebhookSubscription, required
    - `id` string, required
    - `url` string, uri, required: The customer-supplied URL that receives signed POSTs. Always uses `https` in production.
    - `events` WebhookEventType[], required
    - `status` 'active' | 'suspended', required: `suspended` once 20 consecutive deliveries have failed. Re-activate from the web app after fixing your endpoint.
    - `secretTail` string, required: Last 4 chars of the signing secret for UI rendering ("wh_sec_xxxx...wxyz"). The full secret is only returned by `createWebhookSubscription` / `rotateWebhookSubscriptionSecret`.
    - `failureCount` integer, required: Consecutive failed deliveries since the last success.
    - `lastFiredAt` string, date-time, nullable, required
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, required
  - `signingSecret` string, required: Raw HMAC signing secret. Returned here exactly once; the server stores its own copy for signing outbound requests but never reveals it again.

## Other responses

- `400`: The supplied webhook URL failed validation — usually because it was a private/loopback address, used an unsupported scheme, or was not parseable as a URL.
- `401`: Missing, malformed, expired, or revoked API key.
- `402`: The workspace has hit the per-workspace cap on active webhook subscriptions. Delete an unused subscription and try again.
- `429`: Too many requests for this API key. Honour the `Retry-After` response header (seconds) or the `detail.retryAfter` field.

---

[API](https://skmtc.dev/certseal/apis/certseal-com-api.md) · [All operations](https://skmtc.dev/certseal/apis/certseal-com-api/llms.txt) · [OpenAPI document](https://skmtc.dev/certseal/apis/certseal-com-api/revisions/9097f49f49f5?raw)