Setting Up Triggers

Listen for real-time events from third-party services with webhook-based triggers.

Triggers let you receive real-time events from third-party services. When something happens — like a new Slack message, a GitHub push, or a form submission — Weavz delivers the event data to your callback URL.

Weavz supports three trigger source types:

WEBHOOK — the third-party service pushes events to a Weavz-managed URL, which forwards them to your callback
POLLING — Weavz periodically checks the service for new data and delivers any changes to your callback
APP-WEBHOOK — Weavz manages provider webhook registration for integrations that support platform-managed webhooks

Both types deliver events in the same format to your callbackUrl.

Enable a Trigger

Trigger enablement always runs inside a workspace. Include workspaceId so Weavz can scope access, resolve the connection or workspace integration, and apply trigger settings consistently. The code examples assume the workspace has a configured GitHub integration with alias github_prod.

Navigate to Triggers

Open the dashboard and go to Triggers in the sidebar.

Enable a new trigger

Click Enable Trigger. Select an integration (e.g. GitHub, Slack) and pick the trigger event you want to listen for.

Select a connection

Choose the connection that has access to the service you want to monitor.

Set your callback URL

Enter the HTTPS URL where Weavz should deliver events. Optionally add callback headers and metadata.

Save

Click Enable. For webhook triggers, the webhook is automatically registered with the third-party service.

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",
    "workspaceId": "550e8400-e29b-41d4-a716-446655440000",
    "callbackUrl": "https://yourapp.com/webhooks/github-push",
    "integrationAlias": "github_prod"
  }'

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_push',
  workspaceId: '550e8400-e29b-41d4-a716-446655440000',
  callbackUrl: 'https://yourapp.com/webhooks/github-push',
  integrationAlias: 'github_prod',
})
 
console.log('Trigger enabled:', 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_push",
    workspace_id="550e8400-e29b-41d4-a716-446655440000",
    callback_url="https://yourapp.com/webhooks/github-push",
    integration_alias="github_prod",
)
 
print("Trigger enabled:", result["triggerSource"]["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_push',
    workspaceId: '550e8400-e29b-41d4-a716-446655440000',
    callbackUrl: 'https://yourapp.com/webhooks/github-push',
    integrationAlias: 'github_prod',
  }),
})
 
const { triggerSource } = await res.json()
console.log('Trigger enabled:', 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_push",
        "workspaceId": "550e8400-e29b-41d4-a716-446655440000",
        "callbackUrl": "https://yourapp.com/webhooks/github-push",
        "integrationAlias": "github_prod",
    },
)
 
trigger_source = res.json()["triggerSource"]
print("Trigger enabled:", trigger_source["id"])

Response:

json

{
  "triggerSource": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "integrationName": "github",
    "triggerName": "new_push",
    "callbackUrl": "https://yourapp.com/webhooks/github-push",
    "status": "ACTIVE",
    "createdAt": "2025-01-15T10:30:00Z"
  }
}

The examples above show the normal workspace-integration path. Trigger enablement also accepts these options:

Option	Use when
`workspaceIntegrationId`	You have the exact configured workspace integration and want to avoid alias ambiguity
`connectionExternalId`	You intentionally want to select one connection directly instead of using workspace integration resolution
`endUserId`	The trigger should resolve a per-user connection by the end user's `externalId`
`input`	The trigger needs configuration values such as repository, project, folder, or filter settings
`partialIds`	You want explicit trigger input partials; omit to use defaults, or send `[]` to suppress defaults
`callbackHeaders`	Your callback endpoint needs custom authentication or routing headers
`callbackMetadata`	You want tenant, environment, or workflow metadata included with each delivery
`pollingIntervalMinutes`	A polling trigger should run at a specific interval allowed by your plan
`simulate`	You want simulation mode for testing before live delivery

See the Triggers API reference for the complete request body and errors.

Test a Trigger

Get sample event data for a trigger to verify your callback handler before going live.

Go to Triggers, find the trigger you want to test, and click Test. Weavz will show a sample payload for that trigger type.

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')
 
console.log('Sample payload:', sampleData)

python

result = client.triggers.test(
    integration_name="github",
    trigger_name="new_push",
)
 
print("Sample payload:", 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_push',
  }),
})
 
const { sampleData } = await res.json()
console.log('Sample payload:', sampleData)

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_push",
    },
)
 
print("Sample payload:", res.json()["sampleData"])

Response:

json

{
  "sampleData": {
    "ref": "refs/heads/main",
    "repository": {
      "full_name": "example/repo"
    },
    "commits": [
      {
        "message": "Sample commit",
        "author": { "name": "Example User" }
      }
    ]
  }
}

Handling Webhook Events

When a trigger fires, Weavz sends a POST request to your callbackUrl:

http

POST https://yourapp.com/webhooks/github-push
Content-Type: application/json
 
{
  "triggerSourceId": "550e8400-e29b-41d4-a716-446655440000",
  "integrationName": "github",
  "triggerName": "new_push",
  "data": {
    "ref": "refs/heads/main",
    "repository": { "full_name": "my-org/my-repo" },
    "commits": [...]
  },
  "metadata": {},
  "timestamp": "2025-01-15T10:35:00Z"
}

Return a 200 status from your callback endpoint within a few seconds. Events may be delivered more than once — design your handler to be idempotent.

You can include custom headers and metadata when enabling a trigger. Headers are sent with every callback delivery, useful for authentication:

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": "slack",
    "triggerName": "new_message",
    "workspaceId": "550e8400-e29b-41d4-a716-446655440000",
    "callbackUrl": "https://yourapp.com/webhooks/slack",
    "integrationAlias": "office_slack",
    "callbackHeaders": {
      "X-Webhook-Secret": "your_secret_value",
      "X-Tenant-ID": "tenant_123"
    },
    "callbackMetadata": {
      "tenantId": "tenant_123",
      "environment": "production"
    }
  }'

Metadata is included in the metadata field of every callback delivery.

Disable a Trigger

Stop receiving events by disabling the trigger source.

Go to Triggers, find the active trigger, and click Disable. The webhook is automatically deregistered from the third-party service.

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

typescript

await client.triggers.disable('TRIGGER_SOURCE_UUID')

python

client.triggers.disable("TRIGGER_SOURCE_UUID")

typescript

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: 'TRIGGER_SOURCE_UUID' }),
})

python

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

Listing Active Triggers

bash

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

typescript

const { triggers, total } = await client.triggers.list()
 
for (const trigger of triggers) {
  console.log(`${trigger.integrationName}.${trigger.triggerName} → ${trigger.callbackUrl}`)
}

python

result = client.triggers.list()
 
for trigger in result["triggers"]:
    print(f"{trigger['integrationName']}.{trigger['triggerName']} → {trigger['callbackUrl']}")

typescript

const res = await fetch('https://api.weavz.io/api/v1/triggers', {
  headers: { 'Authorization': 'Bearer wvz_your_api_key' },
})
 
const { triggers } = await res.json()
for (const trigger of triggers) {
  console.log(`${trigger.integrationName}.${trigger.triggerName} → ${trigger.callbackUrl}`)
}

python

import httpx
 
res = httpx.get(
    "https://api.weavz.io/api/v1/triggers",
    headers={"Authorization": "Bearer wvz_your_api_key"},
)
 
for trigger in res.json()["triggers"]:
    print(f"{trigger['integrationName']}.{trigger['triggerName']} → {trigger['callbackUrl']}")

Best Practices

Use HTTPS callback URLs — ensure your endpoint is accessible over HTTPS
Verify callbacks — use callbackHeaders with a secret to verify requests are from Weavz
Respond quickly — return a 200 status within a few seconds
Handle duplicates — events may be delivered more than once; make your handler idempotent
Monitor active triggers — regularly review and disable triggers you no longer need