# Trigger structure

> Understand the structure of a trigger configuration that defines what to invoke when an event fires.

A trigger configuration defines what should be invoked when an event is fired. The structure differs depending on whether the action is Cloud Code or a webhook.

## Cloud Code trigger

A Cloud Code trigger invokes a script or module when the event fires. It uses `actionType: cloud-code` and an `actionUrn` that identifies the script or module.

```json
{
  "name" : "example-trigger",
  "eventType" : "com.unity.services.{{SERVICE_NAME}}.{{EVENT_NAME}}.v{{EVENT_VERSION}}",
  "actionUrn" : "urn:ugs:cloud-code:{{SCRIPT}}",
  "actionType" : "cloud-code",
  "filter": "data['parameter'] == 'value'"
}
```

* `name`: The name of the trigger. It must be unique per project.
* `eventType`: Matches the trigger to an event. It is composed of the `eventName` and `eventVersion` fields, corresponding to the `eventName` and `payloadVersion` fields in the event configuration.
* `actionUrn`: What is invoked when the trigger fires. For example, `urn:ugs:cloud-code:TestScript` invokes the `TestScript` Cloud Code script, or `urn:ugs:cloud-code:TestModule/TestFunction` invokes the `TestFunction` function in the `TestModule` Cloud Code module.
* `actionType`: Set to `cloud-code` for Cloud Code triggers.
* `filter`: Optional. A condition that must be met for the trigger to fire. For more information, refer to [Filters](./filters).

## Webhook trigger

A webhook trigger sends an HTTP request to an external URL when the event fires. The webhook trigger configuration requires the following fields:

* `actionType: webhook`
* `actionUrn: urn:ugs:webhook`
* `webhook`: An object containing the request details:
  * `url` (Required): The destination URL.
  * `method` (Optional): The HTTP method (for example `POST` or `GET`). Defaults to `POST`.
  * `headers` (Optional): Custom key-value pairs for the request.
  * `payloadTemplate` (Conditional): The request body template. Required for all content types except `application/json`. For `application/json`, you may omit it to forward the full event payload as-is.

You can inspect and replay failed webhook deliveries from the [dead letter queue](../manage-dlq/dead-letter-queue).

```json
{
  "name" : "example-webhook-trigger",
  "eventType" : "com.unity.services.leaderboards.score-submitted.v1",
  "actionUrn" : "urn:ugs:webhook",
  "actionType" : "webhook",
  "webhook": {
    "url": "https://example.com/events",
    "method": "POST",
    "headers": { "Content-Type": "application/json" },
    "payloadTemplate": "{\"event\": \"score-submitted\", \"data\": {{.}}}"
  }
}
```

For full webhook configuration and template syntax, refer to [Webhooks](/triggers/webhooks.md).

## Overlap with events

Triggers are associated with events. When an event is fired, the associated trigger is invoked. The event and the trigger must share the same `eventName` and `payloadVersion` configuration.

> **Note:**
>
> The `eventType` maps an event to a trigger.

### Scheduled events

Given the following schedule configuration:

```json
{
  "name" : "recurring-schedule",
  "eventName": "example-event",
  "type": "recurring",
  "schedule": "0 0 * * *",
  "payloadVersion": 1,
  "payload": "{\"someBoolean\": true, \"someString\": \"something\"}"
}
```

And the following trigger configuration:

```json
{
  "name" : "example-trigger",
  "eventType" : "com.unity.services.scheduler.example-event.v1",
  "actionUrn" : "urn:ugs:cloud-code:my-script",
  "actionType" : "cloud-code"
}
```

You can associate the trigger with the event type by setting the `eventType` field in the trigger configuration to the `eventName` and `payloadVersion` fields in the schedule configuration.

When the schedule configuration is deployed, the schedule is triggered at the specified time, sending an event to the Triggers service, which in turn invokes the associated Cloud Code resource.

### UGS events

Given you want to associate a trigger with an event type from UGS, you need to specify the event type in the trigger configuration.

For example, if you want to fire a trigger on the [Authentication: Signed Up](../../manage-events/supported-ugs-events#signed-up) event, you can create the following trigger configuration:

```json
{
  "name" : "example-trigger",
  "eventType" : "com.unity.services.player-auth.signed-up.v1",
  "actionUrn" : "urn:ugs:cloud-code:my-script",
  "actionType" : "cloud-code"
}
```

Every time a user signs up, the trigger is fired, invoking the `my-script` Cloud Code script.

### Multiple events per trigger

You can associate the same event with multiple triggers.

> **Note:**
>
> The current limit for the number of triggers per event type is 32.

For example, you can create two triggers that invoke when a user signs up.

The first trigger invokes the `add-cloud-save-data` script to add a Cloud Save data entry for the authenticated user:

```json
{
  "name" : "auth-cloud-save",
  "eventType" : "com.unity.services.player-auth.signed-up.v1",
  "actionUrn" : "urn:ugs:cloud-code:add-cloud-save-data",
  "actionType" : "cloud-code"
}
```

The second trigger invokes the `add-economy-items` endpoint from `Economy` module to add a virtual item to the authenticated user:

```json
{
  "name" : "auth-economy",
  "eventType" : "com.unity.services.player-auth.signed-up.v1",
  "actionUrn" : "urn:ugs:cloud-code:Economy/add-economy-items",
  "actionType" : "cloud-code"
}
```

Every time a user signs up, both triggers fire and invoke the associated Cloud Code resources.

## Additional resources

* [Webhooks](/triggers/webhooks.md)
* [Events](/triggers/manage-events/events.md)
* [Filters](/triggers/tutorials/define-triggers/filters.md)
* [Define triggers in the Unity Dashboard](./unity-dashboard)
* [Define triggers with the CLI](./cli)