Dead letter queue
Understand when events enter the dead letter queue and how to manage them.
阅读时间4 分钟最后更新于 4 个月前
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 errors, times out, or returns
5xx) and retries are exhausted, the event is added to the dead letter queue.429 Too Many Requests - 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 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.
4xxDLQ event status and resolution
Each event in the dead letter queue has a field. Retention and capacity are described in Limits.
statusStatus | Description |
|---|---|
| Awaiting your action (replay or discard). |
| Queued for replay by the system. |
| Currently being replayed. |
| The event has been resolved (replayed or discarded). |
When is , the field indicates how it was resolved:
statusresolvedresolutionActionResolution action | Description |
|---|---|
| The event was successfully re-published. |
| The event was manually removed from the queue. |
注意
The Unity Dashboard combines and into a single filter for convenience. The API and CLI expose them as separate fields.
statusresolutionActionDLQ 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 |
|---|---|---|
| string (UUID) | Unique identifier of the DLQ record. |
| string (UUID) | Project that owns the trigger and event. |
| string (UUID) | Environment (for example production or development). |
| string (UUID) | Original event ID from the Triggers pipeline. |
| string | How the event was produced; for example |
| string | Event type URN; for example |
| string | Subject (resource) the event refers to; for example |
| object | Trigger and context metadata (see below). |
| object | Original event payload; structure depends on the trigger and event type. |
| string | DLQ status: |
| string | How a |
| string (ISO 8601) | When the event was added to the DLQ. |
| string (ISO 8601) | When the DLQ record was last updated. |
The object contains trigger and execution context. Common keys include:
metadataKey | Description |
|---|---|
| Project and environment IDs. |
| Trigger identifier and display name. |
| Action URN (for example |
| Event type that fired the trigger (for example |
The field is the original event body and varies by event type (for example player-auth events include , , ). Refer to Supported UGS events for payload schemas.
payloadplayerIdcreatedAtproviderIdExample 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 Viewer | List and get DLQ events ( |
| Triggers DLQ Manager | All viewer permissions, plus replay and discard events ( |
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.