Dead letter queue
Understand when events enter the dead letter queue and how to manage them.
Read time 3 minutesLast updated a day 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 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.
4xxDLQ event status and resolution
Each event in the dead letter queue has astatusStatus | Description |
|---|---|
| Awaiting your action (replay or discard). |
| Queued for replay by the system. |
| Currently being replayed. |
| The event has been resolved (replayed or discarded). |
statusresolvedresolutionActionResolution action | Description |
|---|---|
| The event was successfully re-published. |
| The event was manually removed from the queue. |
Note
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. |
metadataKey | Description |
|---|---|
| Project and environment IDs. |
| Trigger identifier and display name. |
| Action URN (for example |
| Event type that fired the trigger (for example |
payloadplayerIdcreatedAtproviderId{ "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 ( |