Webhooks & events
Connectors are not only called outward — many receive inbound events (a new CRM deal, an incoming message, an order status change). Those events land in a local journal and can trigger automated tasks, so you can react to what happens in an external service without polling it.
How an inbound event flows
Register the webhook URL
For a connector that supports inbound events, fetch its per-service webhook URL and register it with the provider (in the provider's own settings or developer console).
The provider POSTs the event
When something happens on the provider's side, it POSTs the event to that URL. The platform validates the request and records it in the local journal.
Inspect or react
Read what arrived with query_events, or have a saved task run automatically the moment a matching event lands.
Webhook URLs
Connectors that support inbound events expose a per-service webhook URL you register with the provider. Fetch it programmatically:
The provider then POSTs events to that URL; the platform validates and records them. Whether a given connector supports inbound events is declared in its passport — read it with describe_service before wiring up a webhook.
The event journal
query_events is a read-only tool over the local journal of inbound webhook events already saved by the platform — not a live call to the external service. Use it to inspect what has arrived (for example, the most recent messages or deal updates) without re-fetching from the source.
It has two actions: list to search events with filters, and get to pull the full payload of one event by event_id.
| Field | Type | Description |
|---|---|---|
| actionrequired | string | list to search with filters, or get to fetch one event's full payload by event_id. |
| service | string | Filter by connector — for example telegram, amocrm, bitrix24, wazzup. |
| entity_type | string | Filter by entity — message, lead, deal, contact, order. |
| event_type | string | Filter by event — for example message.received, deal.created, lead.updated. |
| event_id | string | Event UUID — required for action get. |
| days | number | Look back N days (default 7, maximum 90). |
| limit | number | Max results (default 50, maximum 200). |
Triggering tasks on events
A saved task can run automatically when a matching event arrives. Set trigger_type: "webhook" and describe which events to react to:
| Field | Type | Description |
|---|---|---|
| trigger_typerequired | string | Set to webhook for event-driven tasks (the alternative is schedule for cron-driven tasks, or manual for run-only). |
| trigger_config.servicerequired | string | The connector whose events trigger the task. |
| trigger_config.event_types | string[] | Which event types of that service to react to (for example message.received, deal.created). |
| filter_conditions | object[] | Extra conditions on the event payload before the task runs. |
When an inbound event matches, the task executes with the event as its input — turning any connector webhook into an automation.
Webhook vs schedule triggers
A webhook trigger reacts to an external event as it happens; a schedule trigger runs on a cron cadence (minimum interval five minutes). Pick webhook when the work is a response to something that occurred, and schedule when it should run on the clock. See the Tasks API in the interactive explorer.
FAQ
Which connectors can receive inbound webhook events?
Connectors that declare inbound support expose a per-service webhook URL — messengers and CRMs such as telegram, amocrm, bitrix24 and wazzup are typical sources of message, lead and deal events. Read a service passport with describe_service to see whether it supports inbound events.
What is the difference between query_events and a normal connector call?
query_events is read-only over the local journal of inbound events already saved by the platform — it never calls the external service. A normal connector_execute call reaches out to the provider live. Use query_events to inspect what has arrived; use connector_execute to fetch or write.
How long are inbound events kept?
query_events looks back over a window you pass in days (default 7, maximum 90). Query a specific event by its event_id with action: "get" to retrieve the full payload.
How do I run a task automatically when an event arrives?
Create a task with trigger_type: "webhook" and a trigger_config naming the service and the event_types to react to. Add filter_conditions to narrow which payloads run the task. When a matching event arrives, the task executes with the event as its input.
Frequently asked questions
Which connectors can receive inbound webhook events?
Connectors that declare inbound support expose a per-service webhook URL — messengers and CRMs such as telegram, amocrm, bitrix24 and wazzup are typical sources of message, lead and deal events. Read a service passport with describe_service to see whether it supports inbound events.
What is the difference between query_events and a normal connector call?
query_events is read-only over the local journal of inbound events already saved by the platform — it never calls the external service. A normal connector_execute call reaches out to the provider live. Use query_events to inspect what has arrived; use connector_execute to fetch or write.
How long are inbound events kept?
query_events looks back over a window you pass in days (default 7, maximum 90). Query a specific event by its event_id with action get to retrieve the full payload.
How do I run a task automatically when an event arrives?
Create a task with trigger_type webhook and a trigger_config naming the service and the event_types to react to. Add filter_conditions to narrow which payloads run the task. When a matching event arrives, the task executes with the event as its input.