Trigger a deployment

⚠️
Preview — this feature is being built; the design below is the spec.
POST https://app.syntic.ai/v1/deployments/{deployment_id}/trigger

The inbound URL of a webhook deployment. Your system posts JSON here when something happens; Syntic verifies the signature and fires the deployment with the body as {{payload}}. No API key is sent: the request is authenticated by an HMAC signature made with the deployment’s signing secret, the same scheme Syntic uses for its outgoing webhooks.

For how this fits into a full workflow, see Scheduled and triggered runs.

Path parameters

ParameterTypeDescription
deployment_idstringThe deployment id, starting with dep_.

Body

Any JSON object up to 256 KB. Send syntic-signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "t.body">. Requests older than 5 minutes or with a bad signature are refused.

Response

202 Accepted, Content-Type: application/json

{
  "run_id": "drn_01JCA1C3E5G7J9L1N3Q5",
  "status": "started"
}

Examples

BODY='{"order_id": "88123", "total": 412.50}'
T=$(date +%s)
SIG=$(printf '%s.%s' "$T" "$BODY" | openssl dgst -sha256 -hmac "$DEPLOYMENT_SECRET" -hex | sed 's/^.* //')
 
curl -sS https://app.syntic.ai/v1/deployments/dep_01JC9E2G4J6L8N0Q2S4U/trigger \
  -H "Content-Type: application/json" \
  -H "syntic-signature: t=$T,v1=$SIG" \
  -d "$BODY"

Errors

Errors use the error envelope and carry a request_id. Codes specific to this operation:

StatustypecodeWhen
401authentication_errorinvalid_signatureMissing, stale or wrong signature.
404not_found_errordeployment_not_foundNo deployment with that id in this workspace.
409conflict_errordeployment_pausedThe deployment is paused.
413invalid_request_errorpayload_too_largeBody over 256 KB.
429rate_limit_errorrate_limitedMore than 60 calls a minute for this deployment.

Treat payloads as untrusted

The payload becomes part of a user message. Say in the agent’s instructions how to handle content it did not expect, and never let a payload decide which tools may run.

Was this page helpful?