User Intuition

Create Webhook

create_webhook

Create a webhook for an account or one owned study. Choose interview, study lifecycle, participant lifecycle, or quota events. The signing secret is shown once; store it securely.

Input Schema

Name	Required	Description
`hook_url`	Yes
`study_id`	No
`event_types`	No
`organization_id`	No	Organization for this operation and billing. Use list_organizations to choose an active membership.

Output Schema

Name	Required	Description	Default
`result`	Yes	The created webhook. Its signing secret is shown only once.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 22, 2026

changedInput schema / properties / organization_id / description

Previous value: -"Platform admins only: select an organization for this operation. Required when changing another organization’s study or using its wallet."New value: +"Organization for this operation and billing. Use list_organizations to choose an active membership."

Changed2 schema fields changedOct 7, 2026

changedInput schema / properties / event_types / items / enum

Previous value: -[
-  "interview.completed",
-  "study.completed",
-  "report.ready"
-]New value: +[
+  "interview.completed",
+  "study.completed",
+  "report.ready",
+  "study.paused",
+  "study.resumed",
+  "study.stopped",
+  "participant.screened",
+  "participant.started",
+  "participant.quality_scored",
+  "study.quota_reached"
+]

changedInput schema / properties / event_types / maxItems
```
Previous value: -3New value: +10
```

Changed1 schema field changedOct 1, 2026

addedInput schema / properties / organization_id

Added value: +{
+  "description": "Platform admins only: select an organization for this operation. Required when changing another organization’s study or using its wallet.",
+  "maxLength": 128,
+  "minLength": 1,
+  "type": "string"
+}

Changed10 schema fields changedSep 30, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

removedInput schema / additionalProperties
```
Removed value: -false
```

addedInput schema / properties / study_id / pattern

Added value: +"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

changedOutput schema / properties / result / additionalProperties
```
Previous value: -trueNew value: +{}
```
removedOutput schema / properties / result / properties / signing_secret / $ref
```
Removed value: -"#/properties/result/properties/study_id"
```
addedOutput schema / properties / result / properties / signing_secret / type
```
Added value: +[
+  "string",
+  "null"
+]
```
removedOutput schema / properties / result / properties / updated_at / $ref
```
Removed value: -"#/properties/result/properties/created_at"
```
addedOutput schema / properties / result / properties / updated_at / description
```
Added value: +"ISO 8601 timestamp."
```
addedOutput schema / properties / result / properties / updated_at / type
```
Added value: +[
+  "string",
+  "null"
+]
```

First observedSep 30, 2026

TDQS

A3.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare that this is a non-read-only, open-world, non-idempotent, non-destructive creation operation. The description adds important behavior beyond those hints: the signing secret is shown only once and must be stored securely. It still omits authentication requirements and how duplicate webhook creation is handled.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences with no filler, front-loading the core create action and scope before the event choices and the security warning. Every sentence adds useful information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the essential create behavior, scope options, event categories, and the one-time secret. With annotations and an output schema present, it does not need to explain return values, but it could be more complete by noting authentication needs or duplicate-call behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 25%, so the description must compensate. It clarifies that the webhook can target an account or one owned study, which gives meaning to study_id, and groups event_types into interview, study lifecycle, participant lifecycle, and quota categories. It does not explain hook_url semantics, exact event-type usage, or the event_types array constraints beyond what the schema already encodes.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb and resource: 'Create a webhook' for an account or one owned study. It clearly states scope and event categories, but does not explicitly distinguish this from sibling operations like test_webhook, list_webhooks, or rotate_webhook_secret, leaving the agent to infer from the verb alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives some usage context by saying to choose interview, study lifecycle, participant lifecycle, or quota events, and notes account-level versus study-level scope. It does not state when to prefer this tool over alternatives such as test_webhook, nor does it mention prerequisites or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All User Intuition tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?