Skip to main content
Webhooks create an external entrypoint into the Operator manager.

​
What a webhook stores

Each webhook stores:
  • A name
  • A secret token embedded in the trigger URL
  • A prompt template
  • An enabled or disabled state
  • A linked chat thread for history

​
Prompt templates

Webhook prompt templates must include {{payload}}. At trigger time, Operator replaces every {{payload}} placeholder with the request body. The webhook triggers the manager, not a raw instance endpoint. If one agent should handle the event, say that in the prompt. Example template: 
A deployment event just arrived.
Review this payload:

{{payload}}

Summarize what changed, decide whether any instance action is needed, and take that action.

​
Trigger URL

The trigger URL format is: 
https://operator.io/api/webhooks/trigger/<token>

​
Request behavior

  • POST accepts JSON payloads and forwards them into the manager prompt
  • GET works for simple triggers with no payload
  • Payloads above 10 KB are rejected
  • Disabled webhooks return an error until re-enabled

​
Example trigger

curl -X POST "https://operator.io/api/webhooks/trigger/your-token" \
  -H "Content-Type: application/json" \
  -d '{"repo":"acme/app","event":"deploy.failed","sha":"abc123"}'

​
Token rotation

If a webhook URL leaks, regenerate the token from the dashboard. The old URL stops working immediately.

​
Webhooks versus automations

  • Use Automations for scheduled work.
  • Use webhooks for event driven work from external systems.

​
Good webhook sources

  • GitHub Actions
  • CI pipelines
  • Internal tools
  • Form submissions
  • Monitoring alerts