> ## Documentation Index
> Fetch the complete documentation index at: https://developers.datagrid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Event Triggers overview

> Run an agent automatically when an external provider event fires, such as a Procore webhook.

An event trigger (an "App Event automation") runs an agent automatically in response to an external provider event — for example, a Procore webhook such as `Tasks:create`. Instead of invoking the agent yourself, you register a trigger once and Datagrid runs the agent each time the configured event fires.

## Recommended flow

1. Identify the agent you want to run and the provider event that should fire it.
2. Call [Create event trigger](/api-reference/event-triggers/create-event-trigger) with the `trigger_source`, `trigger_event`, and `enabled` state.
3. Inspect the `warnings` array on the response for any prerequisite gaps (see [Warnings](#warnings)).
4. Use [List event triggers](/api-reference/event-triggers/list-event-triggers) to read the current trigger, [Update event trigger](/api-reference/event-triggers/update-event-trigger) to pause/resume or change the event, and [Delete event trigger](/api-reference/event-triggers/delete-event-trigger) to unregister it.

## One trigger per agent

An agent has **at most one** event trigger. Because of this:

* List responses contain zero or one item and `has_more` is always `false`.
* Attempting to [create](/api-reference/event-triggers/create-event-trigger) a second trigger for an agent that already has one is rejected with `409 Conflict`. To change the trigger, update it in place or delete it and create a new one.

## Trigger event format

`trigger_event` uses the `"ResourceName:eventType"` format — the Procore resource name, a colon, then the event type. Examples:

* `"Tasks:create"`
* `"Project Users:update"`

## Procore prerequisites

Event triggers register an underlying provider webhook subscription. For Procore, this depends on configuration that lives **outside** this API:

* The teamspace must have a Procore **company/project mapping** configured.
* The teamspace must have **connected Procore credentials**.

These are set up out of band in teamspace settings. If they are missing or invalid when you create or update a trigger, the trigger is still saved, but the webhook cannot be fully wired up — the gap is reported through the `warnings` array rather than failing the request.

## Warnings

Create and update responses include a `warnings` array. Warnings describe **non-fatal** prerequisite gaps encountered while wiring up the provider webhook — the trigger row is persisted regardless, so the request does not fail. An empty array means the trigger was configured with no issues.

Each warning pairs a stable machine-readable `code` with a human-readable `message`. Branch on `code` rather than parsing `message`, which may change:

```json theme={null}
{
  "warnings": [
    {
      "code": "procore_not_connected",
      "message": "Procore is not connected. Connect Procore in teamspace settings and try again"
    }
  ]
}
```

Known codes include `procore_not_connected`, `procore_not_configured`, `trigger_event_update_failed`, `procore_connection_expired`, `procore_scope_incorrect`, and `procore_registration_rejected`. Any unrecognized warning falls back to `registration_failed`. Treat the code set as open-ended and default to surfacing the `message` for codes you do not recognize.

## Related docs

* [Create event trigger](/api-reference/event-triggers/create-event-trigger)
* [List event triggers](/api-reference/event-triggers/list-event-triggers)
* [Update event trigger](/api-reference/event-triggers/update-event-trigger)
* [Delete event trigger](/api-reference/event-triggers/delete-event-trigger)