Skip to Content
Sophon Docs
API Reference

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:

EventSent when
message.receivedA message arrived
workflow.completedA workflow run succeeded
workflow.failedA workflow run failed
approval.requiredAn approval is waiting
approval.decidedAn approval was decided
agent.errorAn agent turn failed
cron.executedA cron job ran
document.uploaded, document.processed, document.failedA document was uploaded, processed or failed to process
skill.installedA skill was installed
webhook.receivedAn inbound registration received a request

Each delivery is a POST with Content-Type: application/json, the body { event, timestamp, data, sourceId }, and these headers:

HeaderValue
X-Sophon-Signature-256sha256=<hex>: HMAC-SHA256 of the raw body, keyed by the registration's secret
X-Sophon-EventThe event type
X-Sophon-DeliveryA 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:

authTypeThe sender sends
hmacSha256X-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
bearerAuthorization: Bearer <authToken>
customHeaderthe 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.

  1. Give the workflow a webhook trigger.
  2. As the workflow's owner or an Admin, with the ManageWorkflows permission, 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"
  }'
  1. Give the sender the registration's /webhooks/in/<slug> URL and its secret.

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_REQUIRED otherwise) and cannot be combined with an agentId or sessionId (TARGET_CONFLICT).
  • Creating one checks the workflow exists in your tenant (404 TARGET_NOT_FOUND), that you own it or are an Admin (403 not_workflow_owner), and that its trigger is webhook (409 trigger_mismatch).
  • Every request checks again that the workflow still has a webhook trigger, 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 default admin 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.