Triggers API

Triggers let you subscribe to events from third-party services and receive them as webhook deliveries. When an event occurs (e.g., a new Slack message, a GitHub push, or a new row in Google Sheets), Weavz sends a POST request to your configured webhook URL with the event payload.

Weavz supports two trigger mechanisms: webhook-based triggers (real-time, where the third-party service pushes events) and polling-based triggers (Weavz periodically checks for new data and delivers only new items).

Enable Trigger

Activate a trigger to start receiving events. This registers the webhook with the third-party service (for webhook triggers) or starts the polling schedule (for polling triggers).

POST /api/v1/triggers/enable

Request body

Example: GitHub push events

curl -X POST https://your-api.example.com/api/v1/triggers/enable \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "pieceName": "github",
    "triggerName": "new_push",
    "input": {
      "repository": "acme/backend"
    },
    "webhookUrl": "https://your-app.example.com/webhooks/github",
    "connectionId": "conn_github_abc"
  }'

Example response

{
  "id": "trig_abc123",
  "pieceName": "github",
  "triggerName": "new_push",
  "status": "ACTIVE",
  "webhookUrl": "https://your-app.example.com/webhooks/github",
  "connectionId": "conn_github_abc",
  "projectId": null,
  "createdAt": "2025-02-01T12:00:00Z"
}

Disable Trigger

Deactivate a trigger. This unregisters the webhook from the third-party service and stops polling. No further events will be delivered.

POST /api/v1/triggers/disable

Request body

Example request

curl -X POST https://your-api.example.com/api/v1/triggers/disable \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "triggerId": "trig_abc123"
  }'

Example response

{
  "success": true
}

List Triggers

Retrieve all active triggers for the authenticated organization.

GET /api/v1/triggers

Example request

curl https://your-api.example.com/api/v1/triggers \
  -H "Authorization: Bearer wvz_your_api_key"

Example response

{
  "data": [
    {
      "id": "trig_abc123",
      "pieceName": "github",
      "triggerName": "new_push",
      "status": "ACTIVE",
      "webhookUrl": "https://your-app.example.com/webhooks/github",
      "connectionId": "conn_github_abc",
      "projectId": null,
      "createdAt": "2025-02-01T12:00:00Z"
    },
    {
      "id": "trig_def456",
      "pieceName": "google-sheets",
      "triggerName": "new_row",
      "status": "ACTIVE",
      "webhookUrl": "https://your-app.example.com/webhooks/sheets",
      "connectionId": "conn_gsheets_xyz",
      "projectId": "proj_main",
      "createdAt": "2025-02-02T14:30:00Z"
    }
  ]
}

Webhook Delivery Format

When a trigger fires, Weavz sends a POST request to the configured webhookUrl with the following format:

POST https://your-app.example.com/webhooks/github
Content-Type: application/json

{
  "triggerId": "trig_abc123",
  "pieceName": "github",
  "triggerName": "new_push",
  "timestamp": "2025-02-01T12:05:00Z",
  "payload": {
    "ref": "refs/heads/main",
    "repository": {
      "full_name": "acme/backend"
    },
    "commits": [
      {
        "id": "abc123def456",
        "message": "Fix login bug",
        "author": {
          "name": "Alice",
          "email": "alice@example.com"
        }
      }
    ]
  }
}

Delivery details

• The payload field contains the raw event data from the third-party service. Its structure depends on the piece and trigger.
• Weavz includes a triggerId, pieceName, and triggerName in the envelope so you can route events in your webhook handler.
• Your webhook endpoint should return a 2xx status code to acknowledge receipt. Failed deliveries may be retried.

Polling Triggers

Some third-party services do not support webhooks. For these, Weavz uses polling triggers that periodically check for new data.

How polling works

• Weavz polls the third-party API at a configurable interval (default varies by piece, typically 1-5 minutes).
• Each poll compares results against previously seen items using automatic deduplication. Only genuinely new items trigger webhook deliveries.
• Deduplication is handled internally — your webhook handler receives each unique event exactly once under normal conditions.

Polling vs webhook triggers

Error Handling

Common error responses when working with triggers:

// 400 Bad Request — invalid trigger configuration
{
  "error": "VALIDATION_ERROR",
  "message": "Missing required input field: repository"
}

// 404 Not Found — piece or trigger doesn't exist
{
  "error": "NOT_FOUND",
  "message": "Trigger 'new_push' not found in piece 'unknown'"
}

// 400 Bad Request — connection required but not provided
{
  "error": "CONNECTION_REQUIRED",
  "message": "This trigger requires an authenticated connection"
}