Triggers

Receive real-time events from third-party services.

Triggers

Triggers let you receive events from third-party services in real time. When a new Slack message is posted, a GitHub issue is created, or a Google Form response is submitted, Weavz delivers the event payload to your callback URL.

Trigger Types

Integrations use one of three trigger mechanisms:

Webhook

The third-party service sends events directly to Weavz via a webhook endpoint. This is the fastest method — events arrive in real time with minimal latency.

Examples: Slack new message, GitHub push event, Typeform new response

Polling

Weavz periodically checks the third-party service for new data. Polling triggers have slightly higher latency but work with services that don't support webhooks. You can configure the polling interval via pollingIntervalMinutes when enabling a trigger (minimum interval depends on your plan).

Examples: Google Sheets new row, Airtable new record

App Webhook

Similar to webhooks, but Weavz registers the webhook URL with the third-party service programmatically on your behalf. Requires a webhook secret to verify incoming events.

Examples: GitHub repository events, Shopify order events

Enabling a Trigger

To start receiving events, enable a trigger with a callback URL where Weavz will deliver the event payloads.

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_issue",
    "workspaceId": "proj_abc123",
    "input": {
      "repo": "my-org/my-repo"
    },
    "connectionExternalId": "my_github",
    "callbackUrl": "https://your-app.com/webhooks/github-issues"
  }'

typescript

import { WeavzClient } from '@weavz/sdk'
const client = new WeavzClient({ apiKey: 'wvz_your_api_key' })
 
const { triggerSource } = await client.triggers.enable({
  integrationName: 'github',
  triggerName: 'new_issue',
  workspaceId: 'proj_abc123',
  input: {
    repo: 'my-org/my-repo',
  },
  connectionExternalId: 'my_github',
  callbackUrl: 'https://your-app.com/webhooks/github-issues',
})
 
console.log(`Trigger ID: ${triggerSource.id}`)

python

from weavz_sdk import WeavzClient
client = WeavzClient(api_key="wvz_your_api_key")
 
result = client.triggers.enable(
    integration_name="github",
    trigger_name="new_issue",
    workspace_id="proj_abc123",
    input={"repo": "my-org/my-repo"},
    connection_external_id="my_github",
    callback_url="https://your-app.com/webhooks/github-issues",
)
trigger_source = result["triggerSource"]
print(f"Trigger ID: {trigger_source['id']}")

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_issue',
    workspaceId: 'proj_abc123',
    input: { repo: 'my-org/my-repo' },
    connectionExternalId: 'my_github',
    callbackUrl: 'https://your-app.com/webhooks/github-issues',
  }),
})
const data = await res.json()
console.log(`Trigger ID: ${data.triggerSource.id}`)

python

import httpx
res = httpx.post(
    "https://api.weavz.io/api/v1/triggers/enable",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={
        "integrationName": "github",
        "triggerName": "new_issue",
        "workspaceId": "proj_abc123",
        "input": {"repo": "my-org/my-repo"},
        "connectionExternalId": "my_github",
        "callbackUrl": "https://your-app.com/webhooks/github-issues",
    },
)
data = res.json()
print(f"Trigger ID: {data['triggerSource']['id']}")

Callback Delivery

When an event fires, Weavz sends a POST request to your callback URL with the event payload:

json

{
  "triggerId": "trg_abc123",
  "integrationName": "github",
  "triggerName": "new_issue",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "payload": {
    "action": "opened",
    "issue": {
      "number": 42,
      "title": "Bug report",
      "body": "Something is broken..."
    }
  }
}

Your endpoint should return a 200 status code to acknowledge receipt.

Deduplication

Weavz automatically deduplicates events to prevent duplicate deliveries. Each event is assigned a unique identifier based on its content, and Weavz tracks which events have already been delivered. If the same event is received again (common with webhook retries), it will not be sent to your callback URL a second time.

Testing Triggers

Before enabling a trigger in production, test it to see the event schema:

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_issue"
  }'

typescript

import { WeavzClient } from '@weavz/sdk'
const client = new WeavzClient({ apiKey: 'wvz_your_api_key' })
 
const { sampleData } = await client.triggers.test('github', 'new_issue')

python

from weavz_sdk import WeavzClient
client = WeavzClient(api_key="wvz_your_api_key")
 
result = client.triggers.test("github", "new_issue")
sample_data = result["sampleData"]

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_issue',
  }),
})
const data = await res.json()

python

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

This returns sample event data so you can understand the payload shape before building your handler.

Managing Triggers

List active triggers

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, total } = 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()

Disable a trigger

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": "trg_abc123"
  }'

typescript

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

python

from weavz_sdk import WeavzClient
client = WeavzClient(api_key="wvz_your_api_key")
 
client.triggers.disable("trg_abc123")

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: 'trg_abc123',
  }),
})
const data = await res.json()

python

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

Disabling a trigger stops event delivery and cleans up any webhook registrations with the third-party service.

Trigger Lifecycle

stateDiagram-v2
    [*] --> Enable
    Enable --> Active: Webhook/polling setup
    Active --> Disable: Explicitly stopped
    Active --> Error: Connection expired or webhook deregistered
    Disable --> [*]: Cleaned up
    Error --> Disable: Manual disable

Enable — Weavz sets up the webhook or starts polling
Active — events are delivered to your callback URL
Error — if the connection expires or the webhook is deregistered externally, the trigger enters an error state
Disable — you explicitly stop the trigger, cleaning up resources

Next Steps

Actions — execute operations against services
MCP Servers — expose triggers and actions as AI tools
Connections — manage the credentials triggers use

Set up your first trigger in the dashboard or via the API guide.