Create a runtime webhook

POST /v1/admin/runtime/webhooks

• Operation ID: createRuntimeWebhook
• Tags: Runtime webhooks
• Base URL: http://localhost:8787

The signing secret is returned once in the response and is never stored, logged or audited. URLs ending in the platform's own internal webhook path are reserved. Audited as runtime.webhook_create. Authenticates with a Platform staff JWT and permission, like every admin route; the backend calls the separate Runtime service on the caller's behalf (no Runtime API key is ever exposed or accepted).

Workflow: Integration guide.

Authentication: staff Bearer JWT with permission runtime.admin.

Authentication

• Auth: staff Bearer JWT (Authorization: Bearer <access_token>) with the permissions below.
• Required permissions: runtime.admin

Request body

Required: yes.

Content type: application/json

Schema: object

Field	Type	Required	Description
url	string<uri>	yes	Max length: 2000
events	string[]	no	Max items: 100
enabled	boolean	no	-

Responses

201

Webhook created.

• Header x-request-id: Request identifier; quote it when reporting an error. Content type: application/json

Schema: object (RuntimeWebhookCreated)

Field	Type	Required	Description
id	string	yes	-
url	string	yes	-
events	string[]	yes	-
enabled	boolean	yes	-
createdAt	integer	yes	Created (Unix epoch milliseconds).
secret	string	yes	Signing secret. Returned only once, on creation.

Errors

400

Request validation failed.

• Header x-request-id: Request identifier; quote it when reporting an error. Content type: application/json

Schema: object (ValidationErrorBody)

Field	Type	Required	Description
success	boolean	yes	One of: false
error	object	yes	-
error.name	string	yes	One of: "ZodError"
error.issues	object[]	yes	-
error.issues[].code	string	yes	-
error.issues[].path	(string | number)[]	yes	-
error.issues[].message	string	yes	-

Request validation

{
  "success": false,
  "error": {
    "name": "ZodError",
    "issues": [
      {
        "code": "custom",
        "path": [
          "field"
        ],
        "message": "Invalid value"
      }
    ]
  }
}

401

Missing, malformed, expired or wrong-audience Bearer token (missing_token, invalid_token, invalid_audience).

• Header x-request-id: Request identifier; quote it when reporting an error. Content type: application/json

Schema: object (ErrorBody)

Field	Type	Required	Description
error	string	yes	Stable machine-readable error code, e.g. forbidden, not_found.
details	any	no	Optional structured context. For 403 it is { perm }.

Error response

{
  "error": "missing_token"
}

403

Authenticated but lacking the required permission. details.perm lists the accepted permission keys.

• Header x-request-id: Request identifier; quote it when reporting an error. Content type: application/json

Schema: object (ErrorBody), fields as described above.

Error response

{
  "error": "forbidden",
  "details": {
    "perm": "runtime.admin"
  }
}

404

not_found: the runtime does not know this resource.

• Header x-request-id: Request identifier; quote it when reporting an error. Content type: application/json

Schema: object (ErrorBody), fields as described above.

Error response

{
  "error": "not_found"
}

409

webhook_read_only (reserved URL) or conflict (runtime rejected).

• Header x-request-id: Request identifier; quote it when reporting an error. Content type: application/json

Schema: object (ErrorBody), fields as described above.

Error response

{
  "error": "webhook_read_only"
}

422

invalid_request: the runtime rejected the payload (details carry its message).

• Header x-request-id: Request identifier; quote it when reporting an error. Content type: application/json

Schema: object (ErrorBody), fields as described above.

Error response

{
  "error": "invalid_request"
}

500

Unexpected server error (internal). No details are returned.

• Header x-request-id: Request identifier; quote it when reporting an error. Content type: application/json

Schema: object (ErrorBody), fields as described above.

Error response

{
  "error": "internal"
}

503

unavailable: the runtime could not be reached; retry.

• Header x-request-id: Request identifier; quote it when reporting an error. Content type: application/json

Schema: object (ErrorBody), fields as described above.

Error response

{
  "error": "unavailable"
}

Examples

curl

curl -X POST 'http://localhost:8787/v1/admin/runtime/webhooks' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"url":"https://example.com/resource","events":["example"],"enabled":false}'

TypeScript

const accessToken = process.env.ACCESS_TOKEN; // user JWT from your sign-in flow

const response = await fetch("http://localhost:8787/v1/admin/runtime/webhooks", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${accessToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "url": "https://example.com/resource",
    "events": [
      "example"
    ],
    "enabled": false
  }),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const data = response.status === 204 || response.status === 205
  ? undefined
  : response.headers.get("content-type")?.includes("json")
    ? await response.json()
    : await response.text();