Webhooks

Rotate the signing secret

Issues a new signing secret for the same endpoint and returns it — the second and last time a secret is ever returned. This is the …:rotate-secret action; the path segment is {webhook_id}:rotate-secret. The change takes effect on the next delivery, including retries of deliveries already queued, so roll the new secret out to your receiver promptly. There is no overlap window in which both secrets verify.

post/v1/projects/{project_id}/webhooks/{webhook_id}:rotate-secret

Request

  • Base URL: https://api.naturali.ai
  • URL: https://api.naturali.ai/v1/projects/{project_id}/webhooks/{webhook_id}:rotate-secret
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://api.naturali.ai/authorize, token URL https://api.naturali.ai/token, scopes: mcp:access)

Response

A new signing secret was issued.

idstring required

Public webhook ID (whk_ prefix).

project_idstring required
urlstring uri required

Where deliveries are POSTed.

eventsstring[] required

Which events this endpoint receives. Each entry is an exact type (generation.completed), a resource wildcard (generation.*), or * for everything. A bare resource name (generation) matches nothing and is rejected.

descriptionstring nullable required

Operator-facing label.

activeboolean required

Whether deliveries are attempted.

created_atstring date-time required
updated_atstring date-time required
secretstring required

The signing key, returned only by create and rotate. A generated one carries the whsec_ prefix; a chosen one is returned as sent. Never readable afterwards.

Example response

{
  "id": "whk_V1StGXR8Z5jdHi6B",
  "project_id": "proj_V1StGXR8Z5jdHi6B",
  "url": "https://example.com/hooks/naturali",
  "events": [
    "generation.*",
    "message.received"
  ],
  "description": "billing service",
  "active": true,
  "created_at": "2026-07-31T00:00:00.000Z",
  "updated_at": "2026-07-31T00:00:00.000Z",
  "secret": "whsec_V1StGXR8Z5jdHi6BQe4kL2mN"
}

Changes

No recorded changes to this operation across all 1 revision of this API.