Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Mirrored from https://github.com/Camo67/composio.git
Synced Nov 21, 04:45 UTC
| 1 | --- |
| 2 | title: "Triggers" |
| 3 | description: "Triggers (instance) class" |
| 4 | --- |
| 5 | |
| 6 | ## Methods |
| 7 | |
| 8 | ### set_webhook_subscription() |
| 9 | |
| 10 | Create or update the project webhook subscription used for webhook delivery. If a subscription already exists, the first subscription is updated. Otherwise a new subscription is created. By default this subscribes to V3 trigger message events. |
| 11 | |
| 12 | ```python |
| 13 | def set_webhook_subscription(*, webhook_url: str, enabled_events: Sequence[str] | None = ..., version: Union[WebhookVersion, str] = ...) -> WebhookSubscription |
| 14 | ``` |
| 15 | |
| 16 | **Parameters** |
| 17 | |
| 18 | | Name | Type | |
| 19 | |------|------| |
| 20 | | `webhook_url` | `str` | |
| 21 | | `enabled_events?` | `Sequence[str] \| None` | |
| 22 | | `version?` | `Union[WebhookVersion, str]` | |
| 23 | |
| 24 | **Returns** |
| 25 | |
| 26 | `WebhookSubscription` |
| 27 | |
| 28 | **Example** |
| 29 | |
| 30 | ```python |
| 31 | composio.triggers.set_webhook_subscription( |
| 32 | webhook_url=f"{APP_URL}/webhooks/composio", |
| 33 | ) |
| 34 | ``` |
| 35 | |
| 36 | --- |
| 37 | |
| 38 | ### get_type() |
| 39 | |
| 40 | Get a trigger type by its slug Uses the global toolkit version provided when initializing composio instance to fetch trigger for specific toolkit version |
| 41 | |
| 42 | ```python |
| 43 | def get_type(slug: str) -> TriggersTypeRetrieveResponse |
| 44 | ``` |
| 45 | |
| 46 | **Parameters** |
| 47 | |
| 48 | | Name | Type | Description | |
| 49 | |------|------|-------------| |
| 50 | | `slug` | `str` | The slug of the trigger type | |
| 51 | |
| 52 | **Returns** |
| 53 | |
| 54 | `TriggersTypeRetrieveResponse` — The trigger type |
| 55 | |
| 56 | --- |
| 57 | |
| 58 | ### list_active() |
| 59 | |
| 60 | List all active triggers |
| 61 | |
| 62 | ```python |
| 63 | def list_active(trigger_ids: list[str] | None = ..., trigger_names: list[str] | None = ..., auth_config_ids: list[str] | None = ..., connected_account_ids: list[str] | None = ..., show_disabled: bool | None = ..., limit: int | None = ..., cursor: str | None = ...) |
| 64 | ``` |
| 65 | |
| 66 | **Parameters** |
| 67 | |
| 68 | | Name | Type | Description | |
| 69 | |------|------|-------------| |
| 70 | | `trigger_ids?` | `list[str] \| None` | List of trigger IDs to filter by | |
| 71 | | `trigger_names?` | `list[str] \| None` | List of trigger names to filter by | |
| 72 | | `auth_config_ids?` | `list[str] \| None` | List of auth config IDs to filter by | |
| 73 | | `connected_account_ids?` | `list[str] \| None` | List of connected account IDs to filter by | |
| 74 | | `show_disabled?` | `bool \| None` | Whether to show disabled triggers | |
| 75 | | `limit?` | `int \| None` | Limit the number of triggers to return | |
| 76 | | `cursor?` | `str \| None` | Cursor for pagination. Use the nextCursor from the response to get the next page. | |
| 77 | |
| 78 | --- |
| 79 | |
| 80 | ### list() |
| 81 | |
| 82 | List all the trigger types. |
| 83 | |
| 84 | ```python |
| 85 | def list(*, cursor: str | None = ..., limit: int | None = ..., toolkit_slugs: list[str] | None = ...) |
| 86 | ``` |
| 87 | |
| 88 | **Parameters** |
| 89 | |
| 90 | | Name | Type | Description | |
| 91 | |------|------|-------------| |
| 92 | | `cursor?` | `str \| None` | The cursor for pagination | |
| 93 | | `limit?` | `int \| None` | The maximum number of trigger types to return | |
| 94 | | `toolkit_slugs?` | `list[str] \| None` | Filter by toolkit slugs | |
| 95 | |
| 96 | --- |
| 97 | |
| 98 | ### create() |
| 99 | |
| 100 | Create a trigger instance |
| 101 | |
| 102 | ```python |
| 103 | def create(slug: str, *, user_id: str | None = ..., connected_account_id: str | None = ..., trigger_config: Dict[str, Any] | None = ..., type: Literal['webhook', 'poll'] | None = ..., polling_interval: int | None = ...) -> trigger_instance_upsert_response.TriggerInstanceUpsertRes... |
| 104 | ``` |
| 105 | |
| 106 | **Parameters** |
| 107 | |
| 108 | | Name | Type | Description | |
| 109 | |------|------|-------------| |
| 110 | | `slug` | `str` | The slug of the trigger | |
| 111 | | `user_id?` | `str \| None` | The ID of the user that owns the connected account. When `connected_account_id` is omitted, the backend resolves the first active connection for this user and the trigger's toolkit. | |
| 112 | | `connected_account_id?` | `str \| None` | The ID of the connected account to pin | |
| 113 | | `trigger_config?` | `Dict[str, Any] \| None` | The configuration of the trigger | |
| 114 | | `type?` | `Literal['webhook', 'poll'] \| None` | `webhook` or `poll`, for a trigger that supports both. Omit it to let Composio choose. | |
| 115 | | `polling_interval?` | `int \| None` | Minutes between polls, for an instance that polls. Wins over `trigger_config["interval"]`. | |
| 116 | |
| 117 | **Returns** |
| 118 | |
| 119 | `trigger_instance_upsert_response.TriggerInstanceUpsertRes...` — The trigger instance, with the `type` it uses, the `fallback_reason` when it polls after a webhook was unavailable, and its `polling_interval` |
| 120 | |
| 121 | --- |
| 122 | |
| 123 | ### subscribe() |
| 124 | |
| 125 | Subscribe to a trigger and receive trigger events. |
| 126 | |
| 127 | ```python |
| 128 | def subscribe(timeout: float = ..., on_subscription_error: SubscriptionErrorCallback | None = ...) -> TriggerSubscription |
| 129 | ``` |
| 130 | |
| 131 | **Parameters** |
| 132 | |
| 133 | | Name | Type | Description | |
| 134 | |------|------|-------------| |
| 135 | | `timeout?` | `float` | The timeout to wait for the subscription to be established. | |
| 136 | | `on_subscription_error?` | `SubscriptionErrorCallback \| None` | Optional callback invoked when the channel subscription fails: with the raw Pusher payload for asynchronous `pusher:subscription_error` events (for example a later permission rejection), or with `{"error": ...}` for failures raised while establishing the subscription (for example an auth rejection — pysher performs channel auth synchronously). Establish-time failures also make `subscribe()` raise the underlying error promptly instead of waiting out the timeout. Exceptions raised inside the callback are contained and logged, never rethrown. | |
| 137 | |
| 138 | **Returns** |
| 139 | |
| 140 | `TriggerSubscription` — The trigger subscription handler. |
| 141 | |
| 142 | --- |
| 143 | |
| 144 | ### verify_webhook() |
| 145 | |
| 146 | Verify an incoming webhook payload and signature. This method validates that the webhook request is authentic by: 1. Validating the webhook timestamp is within the tolerance window 2. Verifying the HMAC-SHA256 signature using the correct algorithm 3. Parsing the payload and detecting the webhook version (V1, V2, or V3) |
| 147 | |
| 148 | ```python |
| 149 | def verify_webhook(*, id: str, payload: str, secret: str, signature: str, timestamp: str, tolerance: int = ...) -> VerifyWebhookResult |
| 150 | ``` |
| 151 | |
| 152 | **Parameters** |
| 153 | |
| 154 | | Name | Type | Description | |
| 155 | |------|------|-------------| |
| 156 | | `id` | `str` | The webhook message ID from the 'webhook-id' header (format: 'msg_xxx') | |
| 157 | | `payload` | `str` | The raw webhook payload as a string (request body) | |
| 158 | | `secret` | `str` | The webhook secret used to sign the payload (from Composio dashboard) | |
| 159 | | `signature` | `str` | The signature from the 'webhook-signature' header (format: 'v1,base64EncodedSignature') | |
| 160 | | `timestamp` | `str` | The webhook timestamp from the 'webhook-timestamp' header (Unix seconds) | |
| 161 | | `tolerance?` | `int` | Maximum allowed age of the webhook in seconds (default: 300 = 5 minutes). Set to 0 to disable timestamp validation. | |
| 162 | |
| 163 | **Returns** |
| 164 | |
| 165 | `VerifyWebhookResult` — VerifyWebhookResult containing version, normalized payload, and raw payload |
| 166 | |
| 167 | **Raises** |
| 168 | |
| 169 | - `WebhookSignatureVerificationError` — If the signature verification fails |
| 170 | - `WebhookPayloadError` — If the payload cannot be parsed or is invalid |
| 171 | |
| 172 | **Example** |
| 173 | |
| 174 | ```python |
| 175 | # In a Flask webhook handler |
| 176 | @app.route('/webhook', methods=['POST']) |
| 177 | def webhook(): |
| 178 | try: |
| 179 | result = composio.triggers.verify_webhook( |
| 180 | id=request.headers.get('webhook-id', ''), |
| 181 | payload=request.get_data(as_text=True), |
| 182 | signature=request.headers.get('webhook-signature', ''), |
| 183 | timestamp=request.headers.get('webhook-timestamp', ''), |
| 184 | secret=os.environ['COMPOSIO_WEBHOOK_SECRET'], |
| 185 | ) |
| 186 | |
| 187 | # Process the verified payload |
| 188 | print(f"Version: {result['version']}") |
| 189 | print(f"Received trigger: {result['payload']['trigger_slug']}") |
| 190 | return 'OK', 200 |
| 191 | except WebhookSignatureVerificationError: |
| 192 | return 'Unauthorized', 401 |
| 193 | ``` |
| 194 | |
| 195 | --- |
| 196 | |
| 197 | ### parse() |
| 198 | |
| 199 | Parse an incoming webhook request into a typed, normalized trigger payload. Pass a framework request object, or pass `body=` and `headers=` explicitly. When `verify_secret` is provided, the SDK verifies the webhook signature before returning the normalized trigger payload. When it is omitted, the SDK parses the body without verifying the signature. `request` may be any object exposing the request body and headers, such as a Flask, Django, or FastAPI request. The body is read from `.body` (or `.data` / `.get_data()`), and the headers are read from `.headers`. Because this SDK is synchronous, async frameworks must pass an already-read raw body, for example via `body=await request.body()`. |
| 200 | |
| 201 | ```python |
| 202 | def parse(request: Any = ..., *, body: Union[str, bytes, Mapping[str, Any], None] = ..., headers: Union[Mapping[str, Any], None] = ..., verify_secret: Union[str, None, Omit] = ..., tolerance: int = ...) -> VerifyWebhookResult |
| 203 | ``` |
| 204 | |
| 205 | **Parameters** |
| 206 | |
| 207 | | Name | Type | Description | |
| 208 | |------|------|-------------| |
| 209 | | `request?` | `Any` | The incoming webhook request object (Flask/Django/FastAPI) | |
| 210 | | `body?` | `Union[str, bytes, Mapping[str, Any], None]` | The raw request body (str/bytes/parsed mapping); overrides `request` | |
| 211 | | `headers?` | `Union[Mapping[str, Any], None]` | The request headers as a mapping; overrides `request` | |
| 212 | | `verify_secret?` | `Union[str, None, Omit]` | Webhook secret; when set, the signature is verified. Omit it entirely to parse without verification. Passing a present-but-empty value (e.g. an unset `COMPOSIO_WEBHOOK_SECRET`) raises rather than silently skipping verification. | |
| 213 | | `tolerance?` | `int` | Max webhook age in seconds (only used when verifying) | |
| 214 | |
| 215 | **Returns** |
| 216 | |
| 217 | `VerifyWebhookResult` — VerifyWebhookResult containing version, normalized payload, and raw payload |
| 218 | |
| 219 | **Raises** |
| 220 | |
| 221 | - `ValidationError` — If `verify_secret` is empty, or is set but signature headers are missing |
| 222 | - `WebhookSignatureVerificationError` — If signature verification fails |
| 223 | - `WebhookPayloadError` — If the payload cannot be parsed |
| 224 | |
| 225 | **Example** |
| 226 | |
| 227 | ```python |
| 228 | # Flask: verify the signature |
| 229 | @app.route('/webhooks/composio', methods=['POST']) |
| 230 | def webhook(): |
| 231 | try: |
| 232 | result = composio.triggers.parse( |
| 233 | request, |
| 234 | verify_secret=os.environ['COMPOSIO_WEBHOOK_SECRET'], |
| 235 | ) |
| 236 | print(f"Trigger: {result['payload']['trigger_slug']}") |
| 237 | print(f"Event data: {result['payload']['payload']}") |
| 238 | return 'OK', 200 |
| 239 | except exceptions.WebhookSignatureVerificationError: |
| 240 | return 'Unauthorized', 401 |
| 241 | |
| 242 | # FastAPI: parse without verifying after reading the async body |
| 243 | @app.post('/webhooks/composio') |
| 244 | async def webhook(request: Request): |
| 245 | raw = await request.body() |
| 246 | result = composio.triggers.parse(body=raw, headers=request.headers) |
| 247 | return {'trigger': result['payload']['trigger_slug']} |
| 248 | ``` |
| 249 | |
| 250 | --- |
| 251 | |
| 252 | [View source](https://github.com/composiohq/composio/blob/next/python/composio/core/models/triggers.py#L1160) |