Webhooks
Outbound event notifications, inbound webhook registrations, and starting workflows from signed webhooks.
Webhook registrations live under /api/webhooks (see the REST API). A registration is either outbound (Sophon posts events to your URL) or inbound (an external system posts to Sophon). For the Dashboard side, see the Webhooks guide.
Outbound events
An outbound registration subscribes a URL to one or more event types:
| Event | Sent when |
|---|---|
message.received | A message arrived |
workflow.completed | A workflow run succeeded |
workflow.failed | A workflow run failed |
approval.required | An approval is waiting |
approval.decided | An approval was decided |
agent.error | An agent turn failed |
cron.executed | A cron job ran |
document.uploaded, document.processed, document.failed | A document was uploaded, processed or failed to process |
skill.installed | A skill was installed |
webhook.received | An inbound registration received a request |
Each delivery is a POST with Content-Type: application/json, the body { event, timestamp, data, sourceId }, and these headers:
| Header | Value |
|---|---|
X-Sophon-Signature-256 | sha256=<hex>: HMAC-SHA256 of the raw body, keyed by the registration's secret |
X-Sophon-Event | The event type |
X-Sophon-Delivery | A unique id for this delivery |
A failed delivery is retried up to 3 attempts in all.
Workflow events
workflow.completed and workflow.failed are sent when a root workflow run ends, not for test runs, sub-workflow runs, cancelled runs or runs interrupted by a restart. data carries workflowId, workflowName, runId, triggerKind, success, error (redacted, at most 500 characters, null on success), startedAt, completedAt and nodeCount; never inputs, outputs or the definition.
Since v2.2.0 a registration receives a run's event only when the person who created the registration is the run's user or an Admin of the tenant when the event is delivered. To watch every run in a tenant, have an Admin register the hook. A registration stored without a tenant or creator receives no workflow events; re-create it.
Removed in v2.2.0
discussion.completed and discussion.failed were removed with Discussions. A new registration that lists them is rejected, editing a registration drops them, and a stored registration that lists them never receives them.
Inbound registrations
An inbound registration gives an external system a URL, /webhooks/in/<slug>, outside /api and without a Sophon login. The registration authenticates the sender in one of three ways:
authType | The sender sends |
|---|---|
hmacSha256 | X-Signature-256 (or X-Hub-Signature-256): the lowercase hex HMAC-SHA256 of the raw body, keyed by the registration's secret, with an optional sha256= prefix |
bearer | Authorization: Bearer <authToken> |
customHeader | the header named authHeader with the value authToken |
The registration also checks its payload cap (256 KB by default), an optional path pattern and an optional payload transform, then publishes webhook.received and hands the request to its agent or, since v2.2.0, to a workflow.
Start a workflow from a signed webhook
New in 2.2. An inbound registration can target a workflow, so an external system can start it without a Sophon login.
- Give the workflow a
webhooktrigger. - As the workflow's owner or an Admin, with the
ManageWorkflowspermission, create the registration:
curl -X POST https://gw.example.com/api/webhooks \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{
"name": "Deploy notifications",
"direction": "inbound",
"events": ["webhook.received"],
"authType": "hmacSha256",
"target": "workflow:wf_deploy_digest"
}'- Give the sender the registration's
/webhooks/in/<slug>URL and itssecret.
The sender then posts JSON, signed as above:
BODY='{"event":"deployment","status":"success"}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')
curl -X POST "https://gw.example.com/webhooks/in/$SLUG" \
-H "Content-Type: application/json" -H "X-Signature-256: sha256=$SIG" -d "$BODY"The body (after any payload transform) becomes $trigger.data and $input in the workflow. The run executes as the workflow's owner with the workflow's own agent (an agentId in the payload is ignored), and appears in the run list with the trigger kind webhook.
Answers to the sender. 200 { "received": true } once the run is stored; the sender never waits for the run and never sees a run id or result. A missing registration or a workflow that can no longer run answers a bodiless 404; a disabled registration or workflow, or a stopping Gateway, a bodiless 503; too many active runs 429 { "error": "too_many_runs", … }; a payload blocked by prompt-injection screening 409 PROMPT_INJECTION_BLOCKED; a bad signature 401; an oversized body 413.
Rules.
- The target is
workflow:followed by the workflow id, and is fixed when the registration is created. To point a sender at another workflow, delete the registration and create a new one (new slug and secret). - A workflow target needs sender authentication (
WEBHOOK_AUTH_REQUIREDotherwise) and cannot be combined with anagentIdorsessionId(TARGET_CONFLICT). - Creating one checks the workflow exists in your tenant (404
TARGET_NOT_FOUND), that you own it or are an Admin (403not_workflow_owner), and that its trigger iswebhook(409trigger_mismatch). - Every request checks again that the workflow still has a
webhooktrigger, that the registration's creator still owns it or is an Admin, and that it is enabled. After an ownership transfer, the new owner must re-create the registration. - On Personal, the built-in
defaultadmin can target only workflows it owns. - Target registrations are visible only to their creator and Admins. There is no Dashboard or CLI control for creating one; use the API.
- Webhook runs are untrusted: the payload is screened for prompt injection, wrapped as external content in LLM prompts, and code steps cannot use
{{ }}references.
There is no replay protection: the signature covers the body only, so a captured request replayed later starts another run. Keep /webhooks/in behind TLS, allowlist senders and rate-limit it at your reverse proxy (the Gateway's own rate limiter does not cover /webhooks), and make target workflows safe to run twice. Registrations and secrets are stored in plaintext in <dataDir>/config/webhooks.json.
The authenticated workflow webhook
A signed-in caller can also start a workflow that has a webhook trigger directly:
POST /api/workflows/{id}/webhook
Authorization: Bearer <jwt>
Content-Type: application/json
{ "event": "deployment", "status": "success" }It needs ManageWorkflows and the workflow's owner or an Admin. The body is available as {{ $trigger.data }} (for example {{ $trigger.data.status }}). The call waits for the run to end and answers its result with the runId; ?async=true answers 202 { runId, workflowId, status: "pending" } at once. A workflow that is not enabled with a webhook trigger answers 409 trigger_mismatch.
Channel webhooks
Some channels (Slack, Telegram, WhatsApp) receive their messages through webhooks of their own. These are configured during channel setup and are separate from webhook registrations.