Your app settings control how Orceum interacts with your service: where to send webhook events, how to format API keys, what static headers to include on every call, and how to guide users during installation. You configure all of these settings directly in the Orceum Developer Studio.

​
Webhook Configuration

These settings control the bi-directional event flow between Orceum and your app.
  • Webhook URL: The URL where Orceum sends event delivery confirmations (when you push an event).
  • Webhook Secret: A secret created by Orceum and visible in the Developer Studio (typically starting with whs_). You use this to sign events you push to Orceum.
  • Events Enabled: A toggle to allow your app to push proactive events into Orceum.
  • Installation Webhook URL: The URL where Orceum delivers INSTALLED and UNINSTALLED lifecycle events. This can be the same as your Webhook URL or a dedicated endpoint.
See Webhooks and Lifecycle Webhooks.

​
API Key Configuration

Available when your app’s Authentication Method is set to API Key.
  • Header Name: The HTTP header name used to send the API key (e.g., Authorization or X-API-KEY).
  • Header Prefix: An optional prefix before the key value (e.g., Bearer). Leave empty for the raw value.
  • Key Location: Where to inject the key. Choose between Header (default) or Query Parameter.
For OAuth settings, see the dedicated OAuth Configuration guide.

​
Installation Guidance

These fields are shown to users during the API key installation step to help them find and format their credentials.
  • API Key Instructions: Plain-text instructions guiding users where to find their API key in your product.
    • Example: `“Find your API key at Settings → Developer → API in your dashboard. Requires Admin access.”*
  • API Key Format Hint: A hint about the expected format to help users spot mistakes before submitting.
    • Example: "Starts with sk- and is exactly 40 characters long"

​
Static Headers and Query Parameters

Static key-value pairs added to every action call, in addition to the user’s credential headers.
  • Additional Headers: Key-value pairs added as HTTP headers. Useful for service versioning, region routing, or internal tracing.
    • Example: Key: X-API-Version, Value: 2.0
  • Additional Query Params: Key-value pairs appended to the request URL query string.
    • Example: Key: format, Value: json

​
AI Usage Instructions

  • Additional Usage Info: Free-form text injected directly into the assistant’s execution context when running actions for your app. Use this to communicate app-specific behaviors, constraints, or conventions that are difficult to express in individual action descriptions. This is your app’s direct channel to the assistant at execution time. Examples:
    • “Always include the user’s timezone when creating calendar events.”
    • “Task IDs returned by list_tasks expire after 30 minutes — do not cache them.”
    • “Every API response includes a cursor field — use it for pagination rather than page offsets.”
The Additional Usage Info field is a powerful tool for handling edge cases: pagination patterns, field conventions, rate limit awareness, or any behavior that spans across multiple actions.

​
Updating Settings

You can update any of these settings at any time in the Orceum Developer Studio. Changes take effect immediately for all new action calls.