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 for the canonical request/response schema.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 |
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 theGET /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. onlyfailed. - By time window (
since,until) — e.g. the last hour.
Using the log to debug
Reproduce the trigger
Take the action that should fire the webhook (complete a challenge, award points, etc.).
Find the delivery
Query
/webhooks/logs filtered by webhookConfigId and ordered by lastAttemptAt desc. The newest entry is your attempt.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. CheckresponseStatus+responseBody.failed— retries exhausted. Checkerrorand fix the endpoint before retriggering.
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 for a reference implementation.
Retry policy recap
5xx, timeouts, and connection errors trigger a retry with exponential backoff.2xxmarks the deliverydelivered.410 Goneis 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
4xxresponses are terminal and do not retry.
Related pages
Webhook implementation
The protocol — signing, retries, endpoint examples.
Events catalog
Every event type Nudj emits.
Last reviewed: 2026-04 · Related API: GET /api/v2/admin/webhooks/logs