Documentation

Support

Triggers

Open Unity Dashboard

Triggers

Dead letter queue

Understand when events enter the dead letter queue and how to manage them.
Read time 3 minutesLast updated 3 hours ago
The dead letter queue (DLQ) stores events that failed delivery after all retries were exhausted. This includes failed webhook HTTP requests and failed trigger processing. You can list events, replay them to retry delivery, or discard them. To manage the dead letter queue, use the Unity Dashboard, the CLI, or the REST API. For an overview of the options, refer to Manage DLQ.

When events enter the dead letter queue

Events are added to the dead letter queue in the following cases:
  • Webhooks: When the Triggers service cannot successfully deliver a HTTP request to your webhook URL (for example, the endpoint returns 
    5xx
    errors, times out, or returns 
    429 Too Many Requests
    ) and retries are exhausted, the event is added to the dead letter queue.
  • Triggers: When trigger processing fails repeatedly (for example, Cloud Code invocation fails), the event can be added to the dead letter queue.
Events that fail with non-retryable errors (for example 
4xx
client errors for webhooks) are not retried and are not added to the queue. For more information on webhook configuration and retry behavior, refer to Webhooks and Failure handling.

DLQ event status and resolution

Each event in the dead letter queue has a 
status
field. Retention and capacity are described in Limits.

Status

Description

pending
Awaiting your action (replay or discard).
replay_queued
Queued for replay by the system.
processing
Currently being replayed.
resolved
The event has been resolved (replayed or discarded).
When 
status
is 
resolved
, the 
resolutionAction
field indicates how it was resolved:

Resolution action

Description

replayed
The event was successfully re-published.
discarded
The event was manually removed from the queue.
Note
The Unity Dashboard combines 
status
and 
resolutionAction
into a single filter for convenience. The API and CLI expose them as separate fields.

DLQ event structure

Each event in the dead letter queue has the following top-level fields. Understanding this structure helps you debug failed deliveries and build inspection or automation workflows against the API or CLI.

Field

Type

Description

id
string (UUID)Unique identifier of the DLQ record.
projectId
string (UUID)Project that owns the trigger and event.
environmentId
string (UUID)Environment (for example production or development).
eventId
string (UUID)Original event ID from the Triggers pipeline.
sourceType
stringHow the event was produced; for example 
webhook
.
eventType
stringEvent type URN; for example 
com.unity.triggers.action.v1
.
subject
stringSubject (resource) the event refers to; for example 
webhooks.<projectId>
.
metadata
objectTrigger and context metadata (see below).
payload
objectOriginal event payload; structure depends on the trigger and event type.
status
stringDLQ status: 
pending
, 
replay_queued
, 
processing
, or 
resolved
. When 
resolved
, see 
resolutionAction
.
resolutionAction
stringHow a 
resolved
event was handled: 
replayed
or 
discarded
. Omitted when 
status
is not 
resolved
.
createdAt
string (ISO 8601)When the event was added to the DLQ.
updatedAt
string (ISO 8601)When the DLQ record was last updated.
The 
metadata
object contains trigger and execution context. Common keys include:

Key

Description

projectid
, 
environmentid
Project and environment IDs.
triggerid
, 
triggername
Trigger identifier and display name.
triggeractionurn
, 
triggeractiontype
Action URN (for example 
urn:ugs:webhook
) and type (for example 
webhook
).
triggereventtype
Event type that fired the trigger (for example 
com.unity.services.player-auth.signed-in.v1
).
The 
payload
field is the original event body and varies by event type (for example player-auth events include 
playerId
, 
createdAt
, 
providerId
). Refer to Supported UGS events for payload schemas. Example DLQ event: 
{  "id": "81e1698a-485f-4880-aa03-036f716c48b1",  "projectId": "d01a984b-9767-4708-a4d4-643d652138de",  "environmentId": "10bbee9c-7d87-4856-a745-67baa54f6be6",  "eventId": "88a96473-f3e5-4acc-a149-33594870d521",  "sourceType": "webhook",  "eventType": "com.unity.triggers.action.v1",  "subject": "webhooks.d01a984b-9767-4708-a4d4-643d652138de",  "metadata": {    "projectid": "d01a984b-9767-4708-a4d4-643d652138de",    "triggerid": "69191c00-be1c-4cc4-84b9-c2d3a577b427",    "triggername": "webhook-fail",    "environmentid": "10bbee9c-7d87-4856-a745-67baa54f6be6",    "triggeractionurn": "urn:ugs:webhook",    "triggereventtype": "com.unity.services.player-auth.signed-in.v1",    "triggeractiontype": "webhook"  },  "payload": {    "playerId": "hzz4eLMMix5R9Mqe7yJBDDdKcIYg",    "createdAt": "2026-03-12T13:10:29Z",    "providerId": "anonymous"  },  "status": "pending",  "createdAt": "2026-03-12T13:10:43Z",  "updatedAt": "2026-03-12T13:10:43Z"}

Access control

To access the dead letter queue via the API or CLI, the service account must have one of the following roles:

Role

Permissions

Triggers DLQ ViewerList and get DLQ events (
triggers.dlq.list
, 
triggers.dlq.get
).
Triggers DLQ ManagerAll viewer permissions, plus replay and discard events (
triggers.dlq.replay
, 
triggers.dlq.discard
).
In the Unity Dashboard, you assign these roles through service account management. Refer to Authentication for details on setting up service accounts and assigning product roles.

Additional resources