Docs Cloud Webhooks

Cloud webhooks

Cloud webhooks send Space instance lifecycle events to a public HTTP(S) endpoint; use HTTPS for production. Configure them in Cloud cabinet → Webhooks. Space owners, administrators, and editors can create, test, rotate, and deactivate a webhook.

Create and verify a webhook

  1. Enter a descriptive name and a public HTTP(S) URL.
  2. Select one or more events.
  3. Create the webhook and copy the signing secret immediately. The plaintext secret is shown only once.
  4. Use Send test to verify connectivity and signature handling. The test is delivered only to the selected webhook.

While creation or rotation is returning its one-time secret, the cabinet keeps you on the Webhooks page and in the same Space. Once the secret is visible, leaving or switching Spaces asks for confirmation; refreshing the webhook list does not hide it. If Create reports that the secret was not returned, leave the form unchanged and press Create again. When browser session storage is available, the cabinet keeps the exact pending request in this tab across a reload for up to 24 hours, restores it only for the same account and Space, and never sends it automatically. Do not start a different webhook until you have recovered or intentionally discarded that pending request.

For automation, send a stable Idempotency-Key with POST /api/v1/cloud/webhooks?workspace_id={workspace_id}. If the response is lost, repeat the identical request with that key within 24 hours to recover the same webhook ID and signing secret. A changed request with the same key returns 409 idempotency_conflict. The cabinet supplies and reuses this key automatically after an ambiguous failure.

For CLI use, mockarty-cli cloud-webhooks create and rotate-secret accept --request-id. If the CLI generated a key and the request fails, the error prints that key. Retry the identical command with --request-id <printed-key> only when the result is uncertain. Keep the key private alongside the account credentials; it can replay a one-time secret for an authorized caller.

Supported product events are:

  • space.deleted — a Space was deleted. The deletion can still be undone for a time, so treat this as a warning rather than a final state;
  • webhook.test — delivered only by Send test, to the selected webhook.

The wildcard event * subscribes the webhook to every supported event, including
events added later. Leaving the selection empty is the same as choosing *.

An event outside this list is refused when the webhook is created, so a webhook
can never be subscribed to something that will not arrive. To read the current
list from your own code:

curl -H "Authorization: Bearer $MOCKARTY_CLOUD_TOKEN" \
  https://cloud.mockarty.ru/api/v1/cloud/webhooks/events

Verify requests

Every request includes:

  • X-Mockarty-Event — event name;
  • X-Mockarty-Delivery-ID — stable delivery identifier; use it to deduplicate retries;
  • X-Mockarty-Timestamp — Unix timestamp used in the signature;
  • X-Mockarty-Signature — HMAC-SHA256 signature in the form t=<timestamp>,v1=<hex digest>.

Calculate HMAC-SHA256 over <timestamp>.<raw request body> with the signing secret, compare it in constant time, and reject stale timestamps according to your security policy. Verify the raw body before JSON parsing.

Delivery is at least once: a timeout or temporary receiver error may produce a retry. Store X-Mockarty-Delivery-ID after successful processing so a retry does not apply the same business action twice.

Rotate a signing secret

Use Rotate secret when a secret may be exposed or when a migrated webhook reports that rotation is required. Copy the new value immediately and update the receiver before sending another test.

Automation can call:

POST /api/v1/cloud/webhooks/{webhook_id}/rotate-secret?workspace_id={workspace_id}
Idempotency-Key: <stable key for this exact rotation>

The response contains the new secret once. Retry an ambiguous request with the same Idempotency-Key; Mockarty returns the same credential for the same webhook and request. Reusing the key for a different request returns 409 idempotency_conflict.
If the cabinet reports a successful rotation without a secret, press Rotate secret again on that webhook; it reuses the same key. When browser session storage is available, this exact retry survives a reload in the same tab for up to 24 hours. The cabinet never retries automatically and asks before discarding a pending rotation for another webhook or Space.

Creating and rotating webhooks returns credentials, so these operations are intentionally not exposed as AI/MCP tools.

Delivery history and deactivation

Open Deliveries to inspect status and attempt time. A webhook is deactivated instead of erasing its delivery evidence. Deactivated webhooks receive no new events; existing delivery history remains available to authorized workspace users.

If signing material cannot be opened after a key configuration change, restore the original Cloud PII encryption key or rotate the webhook. Do not copy signing secrets into logs, tickets, or chat messages.

Previous
OAuth CLI Login