Skip to main content
POST
/
v1
/
agent
/
:id
/
triggers
Create Trigger
curl --request POST \
  --url https://api.app.shinzo.ai/v1/agent/:id/triggers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "message_template": "<string>",
  "enabled": true
}
'

​
Authentication

Requires JWT token or Platform API key via Authorization: Bearer <token> header.

​
Path Parameters

​
id
string
required
Agent UUID

​
Body Parameters

​
name
string
required
Trigger name (1-255 characters)
​
message_template
string
required
Message to send when webhook fires. Supports {{payload.*}} dot-path substitution from JSON payload
​
enabled
boolean
default:"true"
Whether the trigger is active

​
Example Request

curl -X POST https://api.app.shinzo.ai/v1/agent/:id/triggers \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "GitHub Deployment",
    "message_template": "Deployment {{payload.status}} for {{payload.repository.name}}. Environment: {{payload.environment}}. Commit: {{payload.deployment.sha}}. Review and notify team.",
    "enabled": true
  }'

​
Response

{
  "uuid": "trigger-abc-123",
  "agent_uuid": "agent-xyz-789",
  "name": "GitHub Deployment",
  "message_template": "Deployment {{payload.status}} for {{payload.repository.name}}. Environment: {{payload.environment}}. Commit: {{payload.deployment.sha}}. Review and notify team.",
  "enabled": true,
  "webhook_url": "https://api.app.shinzo.ai/v1/webhooks/triggers/trigger-abc-123",
  "webhook_secret": "whs_a1b2c3d4e5f6g7h8i9j0",
  "created_at": "2026-02-26T10:30:00Z",
  "updated_at": "2026-02-26T10:30:00Z"
}
Save the webhook secret immediately! It’s shown only once at creation time. You’ll need it to authenticate webhook requests.

​
Webhook URL

The returned webhook_url is the endpoint external systems should POST to: 
POST https://api.app.shinzo.ai/v1/webhooks/triggers/trigger-abc-123

​
Webhook Authentication

Include the secret in one of two ways: 
curl -X POST https://api.app.shinzo.ai/v1/webhooks/triggers/trigger-abc-123 \
  -H "X-Webhook-Secret: whs_a1b2c3d4e5f6g7h8i9j0" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "success",
    "repository": {"name": "myapp"},
    "environment": "production",
    "deployment": {"sha": "abc123"}
  }'

​
Option 2: X-Hub-Signature-256 (GitHub-style HMAC)

# Compute HMAC-SHA256 signature
payload='{"event":"test"}'
signature=$(echo -n "$payload" | openssl dgst -sha256 -hmac "whs_a1b2c3d4e5f6g7h8i9j0" | sed 's/^.* //')

# Send request
curl -X POST https://api.app.shinzo.ai/v1/webhooks/triggers/trigger-abc-123 \
  -H "X-Hub-Signature-256: sha256=$signature" \
  -H "Content-Type: application/json" \
  -d "$payload"

​
Template Variable Substitution

The message_template supports {{payload.*}} dot-path access to any field in the webhook JSON payload. Example Payload: 
{
  "event": "deployment",
  "status": "success",
  "repository": {
    "name": "myapp",
    "owner": "acme-corp"
  },
  "commit": {
    "sha": "abc123",
    "author": {
      "name": "John Doe",
      "email": "john@example.com"
    }
  }
}
Template: 
Deployment {{payload.status}} for {{payload.repository.owner}}/{{payload.repository.name}}.
Commit {{payload.commit.sha}} by {{payload.commit.author.name}}.
Rendered: 
Deployment success for acme-corp/myapp.
Commit abc123 by John Doe.

​
Use Cases

​
GitHub Webhooks

  • Deployment status updates
  • Pull request events
  • CI/CD pipeline notifications
  • Issue/PR comments

​
Monitoring & Alerts

  • PagerDuty incidents
  • Datadog/New Relic alerts
  • CloudWatch alarms
  • Sentry error notifications

​
Business Events

  • Stripe payment notifications
  • Customer signup webhooks
  • Order fulfillment status
  • API usage alerts

​
Error Responses

​
400 Bad Request

  • Missing required fields
  • Invalid message template
  • Name exceeds 255 characters

​
404 Not Found

  • Agent not found or you don’t have access

​
429 Too Many Requests

  • Rate limit exceeded

​
See Also