Triggers Admin API

Overview

API for managing Trigger configurations and Dead Letter Queue (DLQ) events.

Limits

One event type can be associated with a maximum of 32 triggers.
Processing of events in order is not guaranteed.
Supports at-least-once delivery semantics. This means that all events are guaranteed to be processed once, but may occasionally be processed multiple times due to network issues.
Triggers do not interact with the return value of the defined action. You should account for this and execute your game logic in the script or module itself.
Cloud Code scripts or modules that rely on external calls using client-side authentication don't work due to the lack of a player context. Refer to Set up Cloud Code: Context attributes for more information.
Cloud Code script and module execution timeouts still apply.
If your trigger interacts with the same service that emits the event, you should define a filter to avoid infinite loops. Infinite loops overprocess the event, cause unexpected behavior in your game, and eventually exhaust your Cloud Code resources for the project, which can lead to a service outage. If you encounter this issue, delete the trigger that causes the loop.

RBAC

The following roles are available for

user

accounts:

Role Name	Scope	Description
`Triggers Configuration Viewer`	Project	Grants read-only access to project configurations.
`Triggers Configuration Editor`	Project	Grants full access to project configurations.
`Triggers DLQ Viewer`	Project	Grants read-only access to the project's DLQ.
`Triggers DLQ Manager`	Project	Grants full access for managing project's DLQ.

Useful Links

Documentation

Download OpenAPI specification:

List existing Triggers Config

List project's environment existing Triggers

Authorizations

ServiceAccount (triggers.configs.list)

HTTP: ServiceAccount

To get started with authentication, visit the Service Account Authentication section.

HTTP Authorization Scheme: basic

Required scopes: triggers.configs.list

Path parameters for "{title}"

projectId

string

필수

The project's Project ID

environmentId

string

필수

The Environment ID of a project

Query parameters for "{title}"

limit

integer

기본: 100

The number of triggers to display per page

after

string

기본: null

A token to get the next page

HTTP response status codes for "{title}":

Bad Request. Returned code indicates one of: - Request parameter validation failure - Other See the errors field for more details.

Invalid Authentication Token

Not Found

Too Many Requests

Internal Server Error

Service Unavailable

Code samples for "{title}":

Request example

curl -X GET \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ "https://services.api.unity.com/triggers/v1/projects/{projectId}/environments/{environmentId}/configs"

Response example

{ "after": "MjAyMy0wNS0wOVQxMzo1OTozNFp8MDAwMDAwMDAtMDAwMC0wMDAwLTAwMDAtMDAwMDAwMDAwMDAw", "configs": [ { "actionType": "cloud-code", "actionUrn": "urn:ugs:cloud-code:MyTestScript", "createdAt": "2023-02-28T12:30:22.590279Z", "eventType": "com.unity.services.leaderboards.score-submitted.v1", "filter": "data[\"leaderboardId\"] == \"my-first-leaderboard\"", "id": "00000000-0000-0000-0000-000000000001", "name": "Trigger Test 1", "updatedAt": "2023-02-28T12:30:22.590279Z" }, { "actionType": "cloud-code", "actionUrn": "urn:ugs:cloud-code:MyTestScript", "createdAt": "2023-03-01T11:45:40.036455Z", "eventType": "com.unity.services.scheduler.example-event-2.v1", "id": "00000000-0000-0000-0000-000000000002", "name": "Trigger Test 2", "updatedAt": "2023-03-01T11:45:40.036455Z" }, { "actionType": "webhook", "actionUrn": "urn:ugs:webhook", "createdAt": "2023-03-01T11:45:40.036455Z", "eventType": "com.unity.services.scheduler.example-event-3.v1", "id": "00000000-0000-0000-0000-000000000003", "name": "Trigger Test 3", "updatedAt": "2023-03-01T11:45:40.036455Z" } ], "limit": 2}

Create Trigger Config

Add Trigger to the project's environment

Authorizations

ServiceAccount (triggers.configs.create)

HTTP: ServiceAccount

To get started with authentication, visit the Service Account Authentication section.

HTTP Authorization Scheme: basic

Required scopes: triggers.configs.create

Path parameters for "{title}"

projectId

string

필수

The project's Project ID

environmentId

string

필수

The Environment ID of a project

Request body for "{title}"

Media Type:

application/json

actionScopeType

string

Scope type of the endpoint this trigger targets, as declared by the caller at creation time. Omit the field (or send

null

) to signal "no scope" -- the triggers service drops the event scope before dispatching the action. When set (e.g.

Player

MultiplayerSession

), the event scope is forwarded to the action executor unchanged. An empty string is not accepted; omit the field instead.

actionType

string

Type of action performed on event occurrence. Currently supported types are: [cloud-code, webhook]

actionUrn

string

필수

A URN description the action that should be taken on event occurrences

eventType

string

필수

Type of the event that should trigger the configured action

filter

string

Define a simple expression using Common Expression Language (https://github.com/google/cel-spec/blob/master/README.md) to apply to the incoming event payload. If the expression result is "true" the trigger action will be executed.

name

string

필수

Display name for the trigger configuration

webhook

object

Webhook configuration. Only present when actionType requires webhook configuration.

headers

object

The headers of the webhook. At most 10 custom header entries are allowed. Available template functions:

secret

(retrieve a secret by key),

hmac_sha256

(sign the request body with HMAC-SHA256),

hmac_sha512

(sign the request body with HMAC-SHA512),

jwt

(mint a JWT token). Example:

Basic {{ secret "auth-token" }}

Bearer {{ jwt }}

{{ hmac_sha256 "my-signing-key" }}

method

string

The method of the webhook

payloadTemplate

string

The payload template of the webhook. Maximum length is 100000 characters (approximately 100 KB for ASCII content). Available template functions:

secret

(retrieve a secret by key). Example:

{"key": "{{ secret "my-secret" }}"}

url

string

The URL of the webhook. Maximum length is 2048 characters. Available template functions:

secret

(retrieve a secret by key). Example:

https://example.com/{{ secret "my-api-key" }}

HTTP response status codes for "{title}":

Bad Request. Returned code indicates one of: - Request parameter validation failure - Other See the errors field for more details.

Invalid Authentication Token

Not Found

Conflict

Trigger limit per event type exceeded

Too Many Requests

Internal Server Error

Service Unavailable

Code samples for "{title}":

Request example

curl -X POST \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ -H "Content-Type: application/json" \ -d '{ "actionScopeType": "string", "actionType": "string", "actionUrn": "string", "eventType": "string", "filter": "string", "name": "string", "webhook": { "headers": {}, "method": "string", "payloadTemplate": "string", "url": "string" }}' \ "https://services.api.unity.com/triggers/v1/projects/{projectId}/environments/{environmentId}/configs"

Response example

{ "actionScopeType": "string", "actionType": "string", "actionUrn": "string", "createdAt": "2024-01-01T00:00:00Z", "environmentId": "string", "eventType": "string", "filter": "string", "id": "string", "name": "string", "projectId": "string", "updatedAt": "2024-01-01T00:00:00Z", "webhook": { "headers": {}, "method": "string", "payloadTemplate": "string", "url": "string" }}

Get Trigger Config

Get the project's environment's Trigger

Authorizations

ServiceAccount (triggers.configs.get)

HTTP: ServiceAccount

To get started with authentication, visit the Service Account Authentication section.

HTTP Authorization Scheme: basic

Required scopes: triggers.configs.get

Path parameters for "{title}"

projectId

string

필수

The project's Project ID

environmentId

string

필수

The Environment ID of a project

configId

string

필수

example: 00000000-0000-0000-0000-000000000000

ID of the trigger config. IDs can be retrieved by listing the triggers configurations.

HTTP response status codes for "{title}":

Bad Request. Returned code indicates one of: - Request parameter validation failure - Other See the errors field for more details.

Invalid Authentication Token

Not Found

Too Many Requests

Internal Server Error

Service Unavailable

Code samples for "{title}":

Request example

curl -X GET \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ "https://services.api.unity.com/triggers/v1/projects/{projectId}/environments/{environmentId}/configs/{configId}"

Response example

{ "actionType": "cloud-code", "actionUrn": "urn:ugs:cloud-code:MyTestScript", "createdAt": "2023-02-28T12:30:22.590279Z", "environmentId": "00000000-0000-0000-0000-000000000000", "eventType": "com.unity.services.leaderboards.score-submitted.v1", "filter": "data[\"leaderboardId\"] == \"my-first-leaderboard\"", "id": "00000000-0000-0000-0000-000000000000", "name": "Trigger Test", "projectId": "00000000-0000-0000-0000-000000000000", "updatedAt": "2023-02-28T12:30:22.590279Z"}

Delete Trigger Config

Delete the project's environment's Trigger

Authorizations

ServiceAccount (triggers.configs.delete)

HTTP: ServiceAccount

To get started with authentication, visit the Service Account Authentication section.

HTTP Authorization Scheme: basic

Required scopes: triggers.configs.delete

Path parameters for "{title}"

projectId

string

필수

The project's Project ID

environmentId

string

필수

The Environment ID of a project

configId

string

필수

example: 00000000-0000-0000-0000-000000000000

ID of the trigger config. IDs can be retrieved by listing the triggers configurations.

HTTP response status codes for "{title}":

No Content

Bad Request. Returned code indicates one of: - Request parameter validation failure - Other See the errors field for more details.

Invalid Authentication Token

Not Found

Too Many Requests

Internal Server Error

Service Unavailable

Code samples for "{title}":

Request example

curl -X DELETE \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ "https://services.api.unity.com/triggers/v1/projects/{projectId}/environments/{environmentId}/configs/{configId}"

Response example

{ "code": 55, "detail": "Failed to parse request body. Error: Unexpected end of JSON input", "status": 400, "title": "Bad Request", "type": "problems/basic"}

List DLQ Events

List failed events in the Dead Letter Queue for the project environment

Authorizations

ServiceAccount (triggers.dlq.list)

HTTP: ServiceAccount

To get started with authentication, visit the Service Account Authentication section.

HTTP Authorization Scheme: basic

Required scopes: triggers.dlq.list

Path parameters for "{title}"

projectId

string

필수

The project's Project ID

environmentId

string

필수

The Environment ID of a project

Query parameters for "{title}"

limit

integer

기본: 50

Maximum number of events to return

after

string

Pagination cursor for the next page

createdFrom

string

Filter events created on or after this timestamp (RFC3339)

createdTo

string

Filter events created on or before this timestamp (RFC3339)

status

string

Filter events by status (pending, replay_queued, processing, resolved)

resolutionAction

string

Filter events by resolution action (replayed, discarded). Only applies to resolved events.

eventId

string

Filter events by original CloudEvent ID

HTTP response status codes for "{title}":

Bad Request. Returned code indicates one of: - Request parameter validation failure - Other See the errors field for more details.

Invalid Authentication Token

Too Many Requests

Internal Server Error

Service Unavailable

Code samples for "{title}":

Request example

curl -X GET \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ "https://services.api.unity.com/triggers/v1/projects/{projectId}/environments/{environmentId}/dlq"

Response example

{ "after": "string", "events": [ { "correlationId": "string", "createdAt": "2024-01-01T00:00:00Z", "environmentId": "string", "eventId": "string", "eventType": "string", "id": "string", "metadata": {}, "payload": {}, "projectId": "string", "resolutionAction": "string", "sourceType": "string", "status": "string", "subject": "string", "updatedAt": "2024-01-01T00:00:00Z" } ], "limit": 0}

Get DLQ Event

Get a specific DLQ event by ID

Authorizations

ServiceAccount (triggers.dlq.get)

HTTP: ServiceAccount

To get started with authentication, visit the Service Account Authentication section.

HTTP Authorization Scheme: basic

Required scopes: triggers.dlq.get

Path parameters for "{title}"

projectId

string

필수

The project's Project ID

environmentId

string

필수

The Environment ID of a project

eventId

string

필수

example: 550e8400-e29b-41d4-a716-446655440000

ID of the DLQ event

HTTP response status codes for "{title}":

Bad Request. Returned code indicates one of: - Request parameter validation failure - Other See the errors field for more details.

Invalid Authentication Token

DLQ Event Not Found

Too Many Requests

Internal Server Error

Service Unavailable

Code samples for "{title}":

Request example

curl -X GET \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ "https://services.api.unity.com/triggers/v1/projects/{projectId}/environments/{environmentId}/dlq/{eventId}"

Response example

{ "correlationId": "string", "createdAt": "2024-01-01T00:00:00Z", "environmentId": "string", "eventId": "string", "eventType": "string", "id": "string", "metadata": {}, "payload": {}, "projectId": "string", "resolutionAction": "string", "sourceType": "string", "status": "string", "subject": "string", "updatedAt": "2024-01-01T00:00:00Z"}

Discard DLQ Event

Mark an event as discarded without reprocessing

Authorizations

ServiceAccount (triggers.dlq.discard)

HTTP: ServiceAccount

To get started with authentication, visit the Service Account Authentication section.

HTTP Authorization Scheme: basic

Required scopes: triggers.dlq.discard

Path parameters for "{title}"

projectId

string

필수

The project's Project ID

environmentId

string

필수

The Environment ID of a project

eventId

string

필수

example: 550e8400-e29b-41d4-a716-446655440000

ID of the DLQ event

HTTP response status codes for "{title}":

Event discarded successfully

Bad Request. Returned code indicates one of: - Request parameter validation failure - Other See the errors field for more details.

Invalid Authentication Token

DLQ Event Not Found

Conflict

Too Many Requests

Internal Server Error

Service Unavailable

Code samples for "{title}":

Request example

curl -X POST \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ "https://services.api.unity.com/triggers/v1/projects/{projectId}/environments/{environmentId}/dlq/{eventId}/discard"

Response example

{ "code": 55, "detail": "Failed to parse request body. Error: Unexpected end of JSON input", "status": 400, "title": "Bad Request", "type": "problems/basic"}

Replay DLQ Event

Queue a failed event for replay.

Authorizations

ServiceAccount (triggers.dlq.replay)

HTTP: ServiceAccount

To get started with authentication, visit the Service Account Authentication section.

HTTP Authorization Scheme: basic

Required scopes: triggers.dlq.replay

Path parameters for "{title}"

projectId

string

필수

The project's Project ID

environmentId

string

필수

The Environment ID of a project

eventId

string

필수

example: 550e8400-e29b-41d4-a716-446655440000

ID of the DLQ event

HTTP response status codes for "{title}":

Event queued for replay

Bad Request. Returned code indicates one of: - Request parameter validation failure - Other See the errors field for more details.

Invalid Authentication Token

DLQ Event Not Found

Conflict

Too Many Requests

Internal Server Error

Service Unavailable

Code samples for "{title}":

Request example

curl -X POST \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ "https://services.api.unity.com/triggers/v1/projects/{projectId}/environments/{environmentId}/dlq/{eventId}/replay"

Response example

{ "code": 55, "detail": "Failed to parse request body. Error: Unexpected end of JSON input", "status": 400, "title": "Bad Request", "type": "problems/basic"}

Discard All Pending DLQ Events

Mark all pending events in the DLQ as discarded. This is an immediate operation.

Authorizations

ServiceAccount (triggers.dlq.discard)

HTTP: ServiceAccount

To get started with authentication, visit the Service Account Authentication section.

HTTP Authorization Scheme: basic

Required scopes: triggers.dlq.discard

Path parameters for "{title}"

projectId

string

필수

The project's Project ID

environmentId

string

필수

The Environment ID of a project

HTTP response status codes for "{title}":

Events discarded successfully

Invalid Authentication Token

Too Many Requests

Internal Server Error

Service Unavailable

Code samples for "{title}":

Request example

curl -X POST \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ "https://services.api.unity.com/triggers/v1/projects/{projectId}/environments/{environmentId}/dlq/discard"

Response example

{ "discardedCount": 0}

Replay All Pending DLQ Events

Queue all pending events in the DLQ for replay.

Authorizations

ServiceAccount (triggers.dlq.replay)

HTTP: ServiceAccount

To get started with authentication, visit the Service Account Authentication section.

HTTP Authorization Scheme: basic

Required scopes: triggers.dlq.replay

Path parameters for "{title}"

projectId

string

필수

The project's Project ID

environmentId

string

필수

The Environment ID of a project

HTTP response status codes for "{title}":

Events queued for replay

Invalid Authentication Token

Too Many Requests

Internal Server Error

Service Unavailable

Code samples for "{title}":

Request example

curl -X POST \ -H "Authorization: Basic <YOUR_CREDENTIALS>" \ "https://services.api.unity.com/triggers/v1/projects/{projectId}/environments/{environmentId}/dlq/replay"

Response example

{ "queuedCount": 0}

Triggers Admin API

Overview

Limits

RBAC

Role Name

Scope

Description

Useful Links

List existing Triggers Config

Path parameters for "{title}"

projectId

environmentId

Query parameters for "{title}"

limit

after

HTTP response status codes for "{title}":

200OK

400Bad Request. Returned code indicates one of: - Request parameter validation failure - Other See the errors field for more details.

401Invalid Authentication Token

404Not Found

429Too Many Requests

500Internal Server Error

503Service Unavailable

Code samples for "{title}":

Request example

Response example

GET/projects/{projectId}/environments/{environmentId}/configs

Create Trigger Config

Path parameters for "{title}"

projectId

environmentId

Request body for "{title}"

actionScopeType

actionType

actionUrn

eventType

filter

name

webhook

headers

method

payloadTemplate

url

HTTP response status codes for "{title}":

200OK

400Bad Request. Returned code indicates one of: - Request parameter validation failure - Other See the errors field for more details.

401Invalid Authentication Token

404Not Found

409Conflict

422Trigger limit per event type exceeded

429Too Many Requests

500Internal Server Error

503Service Unavailable

Code samples for "{title}":

Request example

Response example

POST/projects/{projectId}/environments/{environmentId}/configs

Get Trigger Config

Path parameters for "{title}"

projectId

environmentId

configId

HTTP response status codes for "{title}":

200OK

400Bad Request. Returned code indicates one of: - Request parameter validation failure - Other See the errors field for more details.

401Invalid Authentication Token

404Not Found

429Too Many Requests

500Internal Server Error

503Service Unavailable

Code samples for "{title}":

Request example

Response example

GET/projects/{projectId}/environments/{environmentId}/configs/{configId}

Delete Trigger Config

Path parameters for "{title}"

projectId

environmentId

configId

HTTP response status codes for "{title}":