Triggers

Enable and manage event triggers for integrations.

Triggers

Triggers listen for events from third-party services and deliver them to your callback URL. Weavz supports three trigger types: webhook (real-time push), polling (periodic checks), and app-webhook (platform-managed webhooks).

List Triggers

GET/api/v1/triggers

List all active trigger sources in your organization.

Query Parameters

Field	Type	Required	Description
`workspaceId`	string (uuid)	No	Filter triggers to one workspace
`limit`	integer	No	Number of triggers to return, default `50`, max `100`
`offset`	integer	No	Number of triggers to skip for pagination

Response

json

{
  "triggers": [
    {
      "id": "t1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "orgId": "550e8400-e29b-41d4-a716-446655440000",
      "triggerType": "WEBHOOK",
      "integrationName": "github",
      "triggerName": "new_push",
      "workspaceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "workspaceIntegrationId": "7df5c03e-4df5-4b5f-95a7-5277d8f972db",
      "webhookUrl": "https://api.weavz.io/api/v1/webhooks/github/abc123",
      "callbackUrl": "https://your-app.com/webhooks/github-push",
      "simulate": false,
      "createdAt": "2025-01-15T10:30:00.000Z",
      "lastDelivery": null
    }
  ],
  "total": 1
}

Example

bash

curl https://api.weavz.io/api/v1/triggers \
  -H "Authorization: Bearer wvz_your_api_key"

typescript

import { WeavzClient } from '@weavz/sdk'
 
const client = new WeavzClient({ apiKey: 'wvz_your_api_key' })
 
const { triggers } = await client.triggers.list()

python

from weavz_sdk import WeavzClient
 
client = WeavzClient(api_key="wvz_your_api_key")
 
result = client.triggers.list()
triggers = result["triggers"]

typescript

const res = await fetch('https://api.weavz.io/api/v1/triggers', {
  headers: { 'Authorization': 'Bearer wvz_your_api_key' },
})
const data = await res.json()

python

import httpx
 
res = httpx.get(
    "https://api.weavz.io/api/v1/triggers",
    headers={"Authorization": "Bearer wvz_your_api_key"},
)
data = res.json()

Enable Trigger

POST/api/v1/triggers/enable

Enable a trigger to start receiving events.

Request Body

Field	Type	Required	Description
`integrationName`	string	Yes	Integration name (e.g., `github`, `slack`)
`triggerName`	string	Yes	Trigger name (e.g., `new_push`, `new_message`)
`callbackUrl`	string (uri)	Yes	URL to receive trigger events
`callbackHeaders`	object	No	Custom headers to include with callback requests
`callbackMetadata`	object	No	Metadata passed through with each callback
`connectionExternalId`	string	No	A connection's `externalId` selector. Use this when you want to select one connection directly.
`workspaceId`	string (uuid)	Yes	Workspace scope for connection resolution and partials
`workspaceIntegrationId`	string (uuid)	No	Configured workspace integration instance to target. Prefer this when the same integration has multiple aliases.
`integrationAlias`	string	No	Workspace integration alias to target when `workspaceIntegrationId` is not provided.
`endUserId`	string	No	The end user's `externalId` for per-user connection resolution
`input`	object	No	Trigger configuration values. Defaults and partials are merged before the trigger is enabled
`partialIds`	string[]	No	Partial IDs to apply. If omitted, default partials auto-resolve. Send `[]` to run without defaults.
`pollingIntervalMinutes`	number	No	Polling interval in minutes (1-1440). Only applies to polling triggers. Minimum interval depends on your plan.
`simulate`	boolean	No	Enable simulation mode for testing

Use workspaceIntegrationId or integrationAlias to select the configured alias whose connection strategy and partial defaults should apply.

Response (201)

json

{
  "triggerSource": {
    "id": "t1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "orgId": "550e8400-e29b-41d4-a716-446655440000",
    "triggerType": "WEBHOOK",
    "integrationName": "github",
    "triggerName": "new_push",
    "workspaceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "workspaceIntegrationId": "7df5c03e-4df5-4b5f-95a7-5277d8f972db",
    "integrationAlias": "github_prod",
    "webhookUrl": "https://api.weavz.io/api/v1/webhooks/github/abc123",
    "callbackUrl": "https://your-app.com/webhooks/github-push",
    "createdAt": "2025-01-15T10:30:00.000Z"
  }
}

Example

bash

curl -X POST https://api.weavz.io/api/v1/triggers/enable \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "github",
    "triggerName": "new_push",
    "callbackUrl": "https://your-app.com/webhooks/github-push",
    "integrationAlias": "github_prod",
    "workspaceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "input": {
      "repo": "my-org/my-repo"
    }
  }'

typescript

const { triggerSource } = await client.triggers.enable({
  integrationName: 'github',
  triggerName: 'new_push',
  callbackUrl: 'https://your-app.com/webhooks/github-push',
  integrationAlias: 'github_prod',
  workspaceId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  input: {
    repo: 'my-org/my-repo',
  },
})

python

result = client.triggers.enable(
    integration_name="github",
    trigger_name="new_push",
    callback_url="https://your-app.com/webhooks/github-push",
    integration_alias="github_prod",
    workspace_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    input={
        "repo": "my-org/my-repo",
    },
)

typescript

const res = await fetch('https://api.weavz.io/api/v1/triggers/enable', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    integrationName: 'github',
    triggerName: 'new_push',
    callbackUrl: 'https://your-app.com/webhooks/github-push',
    integrationAlias: 'github_prod',
    workspaceId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    input: {
      repo: 'my-org/my-repo',
    },
  }),
})
const data = await res.json()

python

res = httpx.post(
    "https://api.weavz.io/api/v1/triggers/enable",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={
        "integrationName": "github",
        "triggerName": "new_push",
        "callbackUrl": "https://your-app.com/webhooks/github-push",
        "integrationAlias": "github_prod",
        "workspaceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "input": {
            "repo": "my-org/my-repo",
        },
    },
)
data = res.json()

For webhook triggers, the response includes a webhookUrl that you need to register in the third-party service. For polling triggers, Weavz automatically checks for new data at regular intervals.

Errors

Status	Code	Description
`400`	`VALIDATION_ERROR`	Missing required fields
`403`	`POLLING_INTERVAL_TOO_SHORT`	Polling interval below plan minimum
`404`	`TRIGGER_NOT_FOUND`	Trigger not found on the integration

Disable Trigger

POST/api/v1/triggers/disable

Disable an active trigger and stop receiving events.

Request Body

Field	Type	Required	Description
`triggerSourceId`	string (uuid)	Yes	ID of the trigger source to disable

Response

json

{
  "disabled": true,
  "triggerSourceId": "t1a2b3c4-d5e6-7890-abcd-ef1234567890"
}

Example

bash

curl -X POST https://api.weavz.io/api/v1/triggers/disable \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"triggerSourceId": "t1a2b3c4-d5e6-7890-abcd-ef1234567890"}'

typescript

await client.triggers.disable('t1a2b3c4-d5e6-7890-abcd-ef1234567890')

python

client.triggers.disable("t1a2b3c4-d5e6-7890-abcd-ef1234567890")

typescript

const res = await fetch('https://api.weavz.io/api/v1/triggers/disable', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    triggerSourceId: 't1a2b3c4-d5e6-7890-abcd-ef1234567890',
  }),
})
const data = await res.json()

python

res = httpx.post(
    "https://api.weavz.io/api/v1/triggers/disable",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={"triggerSourceId": "t1a2b3c4-d5e6-7890-abcd-ef1234567890"},
)
data = res.json()

Errors

Status	Code	Description
`400`	`MISSING_ID`	Missing trigger source ID
`404`	`NOT_FOUND`	Trigger source not found

Test Trigger

POST/api/v1/triggers/test

Get sample data for a trigger to understand its event payload format.

Request Body

Field	Type	Required	Description
`integrationName`	string	Yes	Integration name
`triggerName`	string	Yes	Trigger name

Response

json

{
  "sampleData": {
    "ref": "refs/heads/main",
    "repository": {
      "full_name": "owner/repo"
    },
    "commits": [
      {
        "id": "abc123",
        "message": "Update README"
      }
    ]
  }
}

Example

bash

curl -X POST https://api.weavz.io/api/v1/triggers/test \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"integrationName": "github", "triggerName": "new_push"}'

typescript

const { sampleData } = await client.triggers.test('github', 'new_push')

python

result = client.triggers.test("github", "new_push")

typescript

const res = await fetch('https://api.weavz.io/api/v1/triggers/test', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    integrationName: 'github',
    triggerName: 'new_push',
  }),
})
const data = await res.json()

python

res = httpx.post(
    "https://api.weavz.io/api/v1/triggers/test",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={"integrationName": "github", "triggerName": "new_push"},
)
data = res.json()

Errors

Status	Code	Description
`400`	`MISSING_FIELDS`	Missing required fields
`404`	`INTEGRATION_NOT_FOUND`	Integration not found
`404`	`TRIGGER_NOT_FOUND`	Trigger not found