# Dead letter queue > Understand when events enter the dead letter queue and how to manage them. 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](./unity-dashboard), the [CLI](./cli), or the [REST API](./rest-api). For an overview of the options, refer to [Manage DLQ](../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](/triggers/webhooks.md) and [Failure handling](/triggers/failure-handling.md). ## DLQ event status and resolution Each event in the dead letter queue has a `status` field. Retention and capacity are described in [Limits](/triggers/limits.md#dead-letter-queue). | 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` | string | How the event was produced; for example `webhook`. | | `eventType` | string | Event type URN; for example `com.unity.triggers.action.v1`. | | `subject` | string | Subject (resource) the event refers to; for example `webhooks.`. | | `metadata` | object | Trigger and context metadata (see below). | | `payload` | object | Original event payload; structure depends on the trigger and event type. | | `status` | string | DLQ status: `pending`, `replay_queued`, `processing`, or `resolved`. When `resolved`, see `resolutionAction`. | | `resolutionAction` | string | How 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](/triggers/manage-events/supported-ugs-events.md) for payload schemas. Example DLQ event: ```json { "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.list`, `triggers.dlq.get`). | | Triggers DLQ Manager | All 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](/triggers/authentication.md) for details on setting up service accounts and assigning product roles. ## Additional resources * [Webhooks](/triggers/webhooks.md) * [Failure handling](/triggers/failure-handling.md) * [Limits](/triggers/limits.md#dead-letter-queue) * [Manage the dead letter queue in the Unity Dashboard](./unity-dashboard) * [Manage the dead letter queue with the CLI](./cli) * [Manage the dead letter queue with the REST API](./rest-api)