Triggers

A trigger in Weavz listens for events in a third-party service and delivers them to your application. Triggers are the reactive counterpart to actions — while actions let you push data to services, triggers let services push data to you.

Weavz supports two trigger mechanisms: webhook triggers for real-time event delivery and polling triggers for services that do not support webhooks.

Webhook Triggers

Webhook triggers register a URL with the third-party service. When an event occurs, the service sends an HTTP POST request to that URL, and Weavz processes the payload immediately. This provides near-real-time event delivery with no delay.

How It Works

1. Enable: When you enable a webhook trigger, Weavz calls the piece's onEnable handler. This handler registers the webhook with the third-party service (e.g. creating a GitHub webhook or a Slack event subscription).
2. Receive: When an event occurs, the service sends a payload to the Weavz webhook URL. The piece's run handler parses the payload and extracts the relevant data.
3. Deliver: The processed event is delivered to your configured destination (a webhook URL you provide, or stored for polling via the API).
4. Disable: When you disable the trigger, Weavz calls the onDisable handler, which unregisters the webhook from the third-party service.

Webhook URL

Each trigger gets a unique webhook URL that the third-party service calls. This URL is generated automatically when the trigger is enabled and follows the pattern:

https://your-instance.weavz.io/api/v1/webhooks/{triggerId}

The webhook URL is stable for the lifetime of the trigger. Disabling and re-enabling a trigger may generate a new URL depending on the piece's implementation.

Polling Triggers

Polling triggers periodically call the third-party API to check for new data. This is used for services that do not support webhooks or for data sources that are most naturally consumed as a feed (e.g. new rows in a spreadsheet, new emails).

How It Works

1. Enable: The trigger is registered with the Weavz scheduler.
2. Poll: At each interval, Weavz calls the piece's run handler. The handler fetches the latest data from the service, using a stored cursor or timestamp to fetch only new items.
3. Deduplicate: New items are compared against previously seen items using piece-defined deduplication keys. Only genuinely new items are delivered.
4. Deliver: New items are delivered to your configured destination.

Polling Intervals

The polling interval determines how frequently Weavz checks for new data. The available intervals depend on your plan:

Shorter intervals consume more API quota on the third-party service. Choose the longest interval that meets your latency requirements.

Deduplication

Both webhook and polling triggers include built-in deduplication to ensure your application processes each event exactly once. Deduplication works differently for each trigger type:

Webhook Deduplication

Some services may send the same webhook payload multiple times (retries, at-least-once delivery). Weavz deduplicates based on a unique key extracted from the payload by the piece's handler. If the same key is seen within the deduplication window, the duplicate is silently dropped.

Polling Deduplication

Each polling trigger maintains a set of previously seen item identifiers. On each poll cycle, new items are checked against this set. Only items with identifiers not in the set are delivered. The identifier extraction is defined by the piece — typically it is the item's unique ID from the third-party API.

Trigger Lifecycle

A trigger moves through the following states:

1. Created: The trigger is configured but not yet listening for events. No webhook is registered and no polling is scheduled.
2. Enabling: Weavz is registering the webhook or scheduling the polling job. For webhook triggers, this involves making API calls to the third-party service, which may take a moment.
3. Active: The trigger is listening for events and delivering them to your application.
4. Disabling: Weavz is unregistering the webhook or canceling the polling job.
5. Disabled: The trigger is no longer listening. It can be re-enabled at any time.
6. Error: The trigger encountered a problem (e.g. the connection's credentials expired, the third-party service rejected the webhook registration). The error details are stored and visible in the dashboard.

Creating Triggers

Via Dashboard

1. Navigate to Triggers in the sidebar
2. Click Create Trigger
3. Select a piece and trigger type
4. Configure trigger-specific settings (e.g. which events to listen for)
5. Select a connection for the piece
6. Click Enable

Via REST API

# Create and enable a trigger
POST /api/v1/triggers
{
  "pieceName": "github",
  "triggerName": "new_issue",
  "connectionId": "conn_abc123",
  "input": {
    "repo": "my-org/my-repo"
  }
}

# The response includes the trigger ID and webhook URL (if applicable)
{
  "id": "trg_xyz789",
  "status": "ACTIVE",
  "webhookUrl": "https://your-instance.weavz.io/api/v1/webhooks/trg_xyz789"
}

Managing Triggers

# List triggers
GET /api/v1/triggers

# Get trigger details
GET /api/v1/triggers/:id

# Disable a trigger
POST /api/v1/triggers/:id/disable

# Re-enable a trigger
POST /api/v1/triggers/:id/enable

# Delete a trigger
DELETE /api/v1/triggers/:id

Trigger Events

When a trigger fires, the event data is recorded in the activity log. You can view trigger events in the Activity page in the dashboard, which shows the timestamp, trigger name, piece, and a summary of the payload.

Important Considerations

• Connection required: Triggers need an active connection for the piece. If the connection expires or is deleted, the trigger will enter an error state.
• Async webhook registration: Some pieces register webhooks asynchronously. The onEnable handler may return before the webhook is fully registered. Weavz handles this with a pending-operations pattern that awaits all background registrations before confirming the trigger is active.
• Rate limits: Third-party services may rate-limit webhook registrations. If you create many triggers in quick succession, some may temporarily fail. Retry after a short delay.

Related

• Connections — Triggers require an active connection for authentication
• MCP Servers — Expose triggers alongside actions via MCP