Skip to main content
Webhooks tell your backend what happens in a workspace, so you don’t need to poll. A credential provider lets your backend hand each run short-lived credentials, so you don’t store long-lived secrets in Opengeni. Set both up in Settings > Developer for one workspace, or Organization settings > Developer for all shared workspaces. Both are also available through the API and @opengeni/sdk. A workspace’s own credential provider replaces the organization’s for that workspace. Organization settings can target every shared workspace or only those your product created. For stored passwords and keys that agents should discover as items, use a connected or external vault. Vaults and this callback share native authority, but solve different problems: the callback keeps short-lived run credentials renewed and bound to their Git or MCP transport. A stored vault item does not replace that lifecycle.

Signatures

Every request carries an OpenGeni-Signature header: an HMAC-SHA256 over the timestamp and raw body. The signing secret is shown once when you create the webhook or provider. Verify the raw body before parsing it:
Both throw OpenGeniSignatureError for a bad or stale signature. Map the verified workspaceId to your own customer to authorize the request.

Webhooks

The body is a small event; fetch details through the API:
  • Delivery is at least once and may be out of order. Skip ids you’ve handled, and order by sequence within a session.
  • Non-2xx responses are retried with backoff. Each webhook’s page lists recent deliveries and can resend one.
  • Send test event posts a signed webhook.test event.

Credential provider

Before a run’s first command, Opengeni sends your endpoint a signed credentials.request with the workspace, the run, and who started it. Reply within the timeout (10 seconds by default):
Or reply { "status": "not_applicable" } or { "status": "auth_needed", "authNeeded": [...] }. The values reach the sandbox only, not the conversation or logs. Opengeni asks again before expiresAt. Test connection sends a request with purpose: "test" and shows which names a run would get. The full protocol is in the integration reference.