Triggers API

Triggers enable event-driven task execution. Connect external services like GitHub, Slack, or custom webhooks to automatically run agents when events occur.

The Trigger Object


{
  "id": "trig_abc123",
  "userId": "user_xxx",
  "name": "Deploy on Push",
  "environmentId": "env_xxx",
  "agentId": "agent_xxx",
  "source": "github",
  "event": "push",
  "filters": {
    "repo": "org/my-repo",
    "branch": "main"
  },
  "action": {
    "type": "send_message",
    "message": "A push was received. Review the changes."
  },
  "enabled": true,
  "webhookSecret": "a1b2c3...",
  "webhookUrl": "https://api.computer-agents.com/webhooks/triggers/trig_abc123",
  "lastTriggeredAt": "2025-01-15T14:00:00Z",
  "createdAt": "2025-01-01T10:00:00Z",
  "updatedAt": "2025-01-15T14:00:00Z"
}

Attributes

Attribute	Type	Description
`id`	string	Unique identifier (`trig_*`)
`userId`	string	Owner user ID
`name`	string	Trigger name
`environmentId`	string	Environment for execution
`agentId`	string \| null	Optional agent to use
`source`	string	Event source: `github`, `slack`, `email`, `webhook`, `cron`, `custom`
`event`	string	Event type (e.g., `push`, `pull_request`, `message`)
`filters`	object \| null	Filter criteria for matching events
`action`	object	What to do when triggered
`enabled`	boolean	Whether trigger is active
`webhookSecret`	string	HMAC secret for signature verification
`webhookUrl`	string	URL to configure in your external service
`lastTriggeredAt`	string \| null	Last time the trigger fired

Action Object

Field	Type	Description
`type`	string	Always `send_message`
`message`	string	Static message to send to the agent
`template`	string	Template with `{{payload}}` placeholder for webhook data

Use template with {"{"}{"{"}payload{"}"}{"}"} to inject the full webhook payload into the agent’s prompt. This lets the agent see commit details, PR descriptions, etc.

Create Trigger


POST /v1/triggers

Request Body

Parameter	Type	Required	Description
`name`	string	Yes	Trigger name
`environmentId`	string	Yes	Environment for execution
`source`	string	Yes	`github`, `slack`, `webhook`, `email`, `cron`, `custom`
`event`	string	Yes	Event type to match
`action`	object	Yes	Action to perform
`agentId`	string	No	Agent to use
`filters`	object	No	Filter criteria
`enabled`	boolean	No	Enable immediately (default: true)

Example

cURL


curl -X POST https://api.computer-agents.com/v1/triggers \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Review PRs",
    "environmentId": "env_xxx",
    "source": "github",
    "event": "push",
    "filters": {
      "repo": "org/my-repo",
      "branch": "main"
    },
    "action": {
      "type": "send_message",
      "template": "Review this push:\n\n{{payload}}"
    }
  }'

TypeScript


const trigger = await client.triggers.create({
  name: 'Review PRs',
  environmentId: 'env_xxx',
  source: 'github',
  event: 'push',
  filters: { repo: 'org/my-repo', branch: 'main' },
  action: {
    type: 'send_message',
    template: 'Review this push:\n\n{{payload}}'
  }
});
 
console.log(trigger.webhookUrl);    // URL to add to GitHub
console.log(trigger.webhookSecret); // Secret for signature verification

Python


trigger = client.triggers.create(
    name="Review PRs",
    environment_id="env_xxx",
    source="github",
    event="push",
    filters={"repo": "org/my-repo", "branch": "main"},
    action={
        "type": "send_message",
        "template": "Review this push:\n\n{{payload}}",
    },
)
 
print(trigger.webhook_url)    # URL to add to GitHub
print(trigger.webhook_secret) # Secret for signature verification

Response


{
  "trigger": {
    "id": "trig_abc123",
    "name": "Review PRs",
    "source": "github",
    "event": "push",
    "enabled": true,
    "webhookSecret": "a1b2c3d4e5f6...",
    "webhookUrl": "https://api.computer-agents.com/webhooks/triggers/trig_abc123",
    "createdAt": "2025-01-15T10:00:00Z"
  }
}

Webhook Setup

After creating a trigger, configure the external service to send webhooks to your trigger’s URL.

GitHub

Go to your repo Settings → Webhooks → Add webhook
Payload URL: Use the webhookUrl from the trigger response
Content type: application/json
Secret: Use the webhookSecret from the trigger response
Events: Select the event that matches your trigger (e.g., “Just the push event”)

The webhookSecret is only returned when the trigger is created. Store it securely — you’ll need it to configure the webhook in GitHub.

Slack

Go to your Slack app settings → Event Subscriptions
Set the Request URL to your trigger’s webhookUrl
Use the webhookSecret as your Signing Secret
Subscribe to the events you want to trigger on

Custom / Generic Webhooks

For any service that supports webhooks, send a POST request to the trigger’s webhookUrl with:


# Compute HMAC-SHA256 signature
PAYLOAD='{"event": "deploy", "version": "2.0"}'
SIG=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET" | sed 's/.*= //')
 
curl -X POST "$WEBHOOK_URL" \
  -H "X-Webhook-Signature: sha256=$SIG" \
  -H "Content-Type: application/json" \
  -d "$PAYLOAD"

Webhook Ingestion Endpoint


POST /webhooks/triggers/:triggerId

This is the public endpoint that external services call. No API key required — authentication is via HMAC signature verification.

Signature Verification

Source	Header	Format
GitHub	`X-Hub-Signature-256`	`sha256=<HMAC-SHA256 hex>`
Slack	`X-Slack-Signature`	`v0=<HMAC-SHA256 hex>`
Generic	`X-Webhook-Signature`	`sha256=<HMAC-SHA256 hex>`

Event Matching

For GitHub webhooks, the event type is read from the X-GitHub-Event header and matched against the trigger’s event field. If the event doesn’t match, the webhook is acknowledged (200) but skipped.

Filter Matching

Filter	Payload Field	Description
`repo`	`repository.full_name`	GitHub repository (e.g., `org/repo`)
`branch`	`ref`	Branch name (strips `refs/heads/` prefix)

Response


{
  "acknowledged": true,
  "executionId": "texec_abc123",
  "threadId": "thread_xxx"
}

Skipped Response

When the event or filters don’t match:


{
  "acknowledged": true,
  "skipped": true,
  "reason": "Event 'issues' does not match trigger event 'push'"
}

List Triggers


GET /v1/triggers

Query Parameters

Parameter	Type	Description
`environmentId`	string	Filter by environment
`source`	string	Filter by source
`enabled`	boolean	Filter by enabled status
`limit`	number	Max results
`offset`	number	Pagination offset

Example

cURL


curl "https://api.computer-agents.com/v1/triggers?source=github" \
  -H "Authorization: Bearer $API_KEY"

TypeScript


const triggers = await client.triggers.list({ source: 'github' });

Python


triggers = client.triggers.list(source="github")

Response


{
  "object": "list",
  "data": [
    {
      "id": "trig_abc123",
      "name": "Review PRs",
      "source": "github",
      "event": "push",
      "enabled": true,
      "webhookUrl": "https://api.computer-agents.com/webhooks/triggers/trig_abc123"
    }
  ],
  "has_more": false,
  "total_count": 3
}

Get Trigger


GET /v1/triggers/:id

Example

cURL


curl https://api.computer-agents.com/v1/triggers/trig_abc123 \
  -H "Authorization: Bearer $API_KEY"

TypeScript


const trigger = await client.triggers.get('trig_abc123');

Python


trigger = client.triggers.get("trig_abc123")

Update Trigger


PATCH /v1/triggers/:id

Request Body

Parameter	Type	Description
`name`	string	New name
`agentId`	string \| null	New agent
`event`	string	New event type
`filters`	object \| null	New filters
`action`	object	New action
`enabled`	boolean	Enable/disable

Example

cURL


curl -X PATCH https://api.computer-agents.com/v1/triggers/trig_abc123 \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event": "pull_request"}'

TypeScript


const trigger = await client.triggers.update('trig_abc123', {
  event: 'pull_request'
});

Python


trigger = client.triggers.update("trig_abc123", event="pull_request")

Delete Trigger


DELETE /v1/triggers/:id

Example

cURL


curl -X DELETE https://api.computer-agents.com/v1/triggers/trig_abc123 \
  -H "Authorization: Bearer $API_KEY"

TypeScript


await client.triggers.delete('trig_abc123');

Python


client.triggers.delete("trig_abc123")

Enable/Disable Trigger

Enable


PATCH /v1/triggers/:id/enable

Disable


PATCH /v1/triggers/:id/disable

Example

cURL


# Enable
curl -X PATCH https://api.computer-agents.com/v1/triggers/trig_abc123/enable \
  -H "Authorization: Bearer $API_KEY"
 
# Disable
curl -X PATCH https://api.computer-agents.com/v1/triggers/trig_abc123/disable \
  -H "Authorization: Bearer $API_KEY"

TypeScript


// Enable
await client.triggers.update('trig_abc123', { enabled: true });
 
// Disable
await client.triggers.update('trig_abc123', { enabled: false });

Python


# Enable
client.triggers.update("trig_abc123", enabled=True)
 
# Disable
client.triggers.update("trig_abc123", enabled=False)

Test Fire Trigger

Manually fire a trigger with an optional test payload.


POST /v1/triggers/:id/test

Request Body

Parameter	Type	Description
`payload`	object	Optional test payload

Example

cURL


curl -X POST https://api.computer-agents.com/v1/triggers/trig_abc123/test \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"payload": {"ref": "refs/heads/main", "commits": [{"message": "test"}]}}'

TypeScript


const result = await client.triggers.test('trig_abc123', {
  payload: { ref: 'refs/heads/main', commits: [{ message: 'test' }] }
});

Python


result = client.triggers.test(
    "trig_abc123",
    payload={"ref": "refs/heads/main", "commits": [{"message": "test"}]},
)

Response


{
  "execution": {
    "id": "texec_abc123",
    "triggerId": "trig_abc123",
    "threadId": "thread_xxx",
    "status": "running",
    "createdAt": "2025-01-15T14:00:00Z"
  }
}

List Trigger Executions


GET /v1/triggers/:id/executions

Query Parameters

Parameter	Type	Description
`limit`	number	Max results
`offset`	number	Pagination offset

Example

cURL


curl "https://api.computer-agents.com/v1/triggers/trig_abc123/executions" \
  -H "Authorization: Bearer $API_KEY"

TypeScript


const executions = await client.triggers.listExecutions('trig_abc123');

Python


executions = client.triggers.list_executions("trig_abc123")

Response


{
  "object": "list",
  "data": [
    {
      "id": "texec_abc123",
      "triggerId": "trig_abc123",
      "threadId": "thread_xxx",
      "status": "completed",
      "eventPayload": { "ref": "refs/heads/main" },
      "createdAt": "2025-01-15T14:00:00Z"
    }
  ],
  "has_more": false,
  "total_count": 10
}

Errors

Status	Error	Description
400	`Bad Request`	Missing required fields
401	`Unauthorized`	Webhook signature verification failed
402	`Payment Required`	Monthly usage allowance exhausted
404	`Not Found`	Trigger not found
409	`Conflict`	Trigger is disabled

Schedules - Time-based task automation
Threads - Execution contexts
Agents - Agent configuration

Triggers API

The Trigger Object

Attributes

Action Object

Create Trigger

Request Body

Example

cURL

TypeScript

Python

Response

Webhook Setup

GitHub

Slack

Custom / Generic Webhooks

Webhook Ingestion Endpoint

Signature Verification

Event Matching

Filter Matching

Response

Skipped Response

List Triggers

Query Parameters

Example

cURL

TypeScript

Python

Response

Get Trigger

Example

cURL

TypeScript

Python

Update Trigger

Request Body

Example

cURL

TypeScript

Python

Delete Trigger

Example

cURL

TypeScript

Python

Enable/Disable Trigger

Enable

Disable

Example

cURL

TypeScript

Python

Test Fire Trigger

Request Body

Example

cURL

TypeScript

Python

Response

List Trigger Executions

Query Parameters

Example

cURL

TypeScript

Python

Response

Errors

Related