Quickstart.

In under two minutes — mint a key, send an event, watch the agent respond.

Before you begin

• You have an Olbrain organization and at least one agent created in Studio.
• You have an agent_id — copy it from the agent detail page in Studio.
• You can run curl from a terminal (or use any HTTP client).

Step 1 · Mint an Access Key

In Studio, open Organization → Access Keys and click Create key. Give it a recognizable name (e.g. webhook — shopify production), grant the agents:invoke permission, and copy the key shown. It starts with ak_ and is shown once.

If you'd rather use the Studio API directly:

curl -X POST https://studio.olbrain.com/api/v1/organizations/<org_id>/access-keys \
  -H "Authorization: Bearer <your-user-token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"webhook key","permissions":["agents:invoke"]}'

Step 2 · Send your first webhook

POST to the webhook endpoint, scoped to your agent_id:

curl -X POST https://webhook.olbrain.com/api/agents/webhook/agt_01HAKZ... \
  -H "Authorization: Bearer ak_<your-access-key>" \
  -H "Content-Type: application/json" \
  -d '{"message":"hello from my backend"}'

What you get back

For a conversational agent, the response confirms the message was accepted. For a workflow agent, the response contains a run_id you can later inspect or control.

Step 3 · Verify in Studio

Open the agent in Studio. Conversational agents show the message in the activity feed; workflow agents show a new run under Runs — click in to see steps, inputs, and outputs.

What to read next