> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nudj.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook Delivery Logs

> Inspect webhook delivery history, retry state, and failure reasons via the Admin API.

Every webhook Nudj dispatches is tracked in the delivery log. Use the log to debug failed deliveries, confirm a specific event reached your endpoint, or audit integration health.

<Info>
  Webhook configs live under `/api/v2/admin/webhooks/configs`. Delivery logs live under `/api/v2/admin/webhooks/logs` — the two endpoints are separate. See the [Admin API reference](/api-reference/admin/get-webhooks-logs) for the canonical request/response schema.
</Info>

## What gets logged

Every delivery attempt records:

| Field             | Meaning                                                                   |
| ----------------- | ------------------------------------------------------------------------- |
| `deliveryId`      | Unique per delivery, stable across retries — matches `X-Nudj-Delivery-Id` |
| `webhookConfigId` | Which configured endpoint this delivery targets                           |
| `event`           | Event type from the [catalog](/enterprise/webhooks-events-catalog)        |
| `url`             | Target URL at time of delivery                                            |
| `status`          | `pending`, `delivered`, `retrying`, `failed`                              |
| `attempts`        | Number of delivery attempts so far                                        |
| `lastAttemptAt`   | Timestamp of the most recent attempt                                      |
| `nextAttemptAt`   | Timestamp of the next scheduled attempt (if `retrying`)                   |
| `responseStatus`  | HTTP status code from the last response                                   |
| `responseBody`    | Short response excerpt (for diagnostics)                                  |
| `error`           | Error message if the request failed before getting a response             |

## Listing deliveries

Query the logs via the Admin API — see the [`GET /webhooks/logs`](/api-reference/admin/get-webhooks-logs) reference for the full filter surface. Typical filters:

* By config (`webhookConfigId`) — only this endpoint's deliveries.
* By event (`event`) — only this event type.
* By status (`status`) — e.g. only `failed`.
* By time window (`since`, `until`) — e.g. the last hour.

## Using the log to debug

<Steps>
  <Step title="Reproduce the trigger">
    Take the action that should fire the webhook (complete a challenge, award points, etc.).
  </Step>

  <Step title="Find the delivery">
    Query `/webhooks/logs` filtered by `webhookConfigId` and ordered by `lastAttemptAt desc`. The newest entry is your attempt.
  </Step>

  <Step title="Check the status">
    * `delivered` — your endpoint returned 2xx. If your system didn't process it, the issue is on your side.
    * `retrying` — the endpoint returned a retryable error. Check `responseStatus` + `responseBody`.
    * `failed` — retries exhausted. Check `error` and fix the endpoint before retriggering.
  </Step>

  <Step title="Verify signature match">
    If your endpoint is returning 401 with "invalid signature", confirm you're HMAC-ing the **raw** body — re-serialised JSON produces a different byte sequence. See [Webhook Implementation](/enterprise/webhook-rewards#signature-verification) for a reference implementation.
  </Step>
</Steps>

## Retry policy recap

* `5xx`, timeouts, and connection errors trigger a retry with exponential backoff.
* `2xx` marks the delivery `delivered`.
* `410 Gone` is the documented signal for permanent removal — Nudj honours this so your side can fence off a deprecated endpoint cleanly (PR #2124 shipped this behaviour on Shopify's disabled topics).
* Other `4xx` responses are terminal and do not retry.

## Related pages

<CardGroup cols={2}>
  <Card title="Webhook implementation" icon="webhook" href="/enterprise/webhook-rewards">
    The protocol — signing, retries, endpoint examples.
  </Card>

  <Card title="Events catalog" icon="list" href="/enterprise/webhooks-events-catalog">
    Every event type Nudj emits.
  </Card>
</CardGroup>

> Last reviewed: 2026-04 · Related API: `GET /api/v2/admin/webhooks/logs`