Webhooks

Stay informed about important events in your Duro library with real-time webhook notifications.

Webhooks follow a "Ping then Pull" pattern - you receive lightweight event notifications with key metadata, then fetch full resource details using our GraphQL API when needed.

Overview

Duro webhooks let your applications receive real-time notifications when important events occur in your library. Instead of constantly polling for changes, webhooks push event notifications directly to your specified endpoints, helping you build responsive integrations that react immediately to data changes.

Key Benefits

• Real-time updates - Get notified instantly when data changes

• Efficient integration - No need for constant API polling

• Selective subscriptions - Subscribe only to the events you care about

• Reliable delivery - Built-in retry mechanisms with exponential backoff

• Secure - HMAC-SHA256 signature verification to ensure authenticity

How Webhooks Work

1. Event occurs - Something happens in Duro (e.g., a component is updated)

2. Notification sent - Duro sends a lightweight JSON payload to your webhook URL

3. Fetch full data - Your application uses the provided metadata to fetch complete details via GraphQL as needed

This pattern keeps webhook payloads small and fast while giving you access to all the data you need.

---

Available Events

Webhooks are scoped to a specific library. Each webhook can subscribe to one or more event types.

Component Events

These events fire when components in your library are created, updated, or deleted:

GraphQL Enum	Payload Value	Description
COMPONENT_CREATED	components.created	A new component was created in the library
COMPONENT_UPDATED	components.updated	An existing component was modified
COMPONENT_DELETED	components.deleted	A component was removed from the library

When subscribing to events via GraphQL, use the enum name (e.g., COMPONENT_CREATED). When processing webhook payloads, the event field contains the string value (e.g., components.created).

Change Order Events

Track the full lifecycle of change orders in your library with these events:

GraphQL Enum	Payload Value	Description
CHANGE_ORDER_OPENED	change_orders.opened	A change order transitioned from draft to open status
CHANGE_ORDER_UPDATED	change_orders.updated	Change order details were modified (name, description, etc.)
CHANGE_ORDER_DELETED	change_orders.deleted	A change order was archived
CHANGE_ORDER_STAGE_TRANSITION	change_orders.stage_transition	Change order moved to a different workflow stage
CHANGE_ORDER_STAGE_REVIEWER_DECISION	change_orders.stage_reviewer_decision	A reviewer approved or rejected their stage
CHANGE_ORDER_RESOLUTION	change_orders.resolution	Change order was fully approved, rejected, or withdrawn
CHANGE_ORDER_CLOSED	change_orders.closed	A change order transitioned into the terminal closed state after resolution

Semantic Event Priority: When a change triggers multiple events (e.g., updating status from draft to open), Duro sends the more specific semantic event (CHANGE_ORDER_OPENED) rather than the generic CHANGE_ORDER_UPDATED. This prevents duplicate notifications and makes event handling more predictable.

---

Setting Up Webhooks

Create a Webhook

To create a webhook, you'll need:

• The x-library header set to specify which library to monitor

• A url - your HTTPS endpoint that will receive notifications

• A list of events - which event types to subscribe to

Required Headers: All webhook operations require the x-api-key, x-organization, and x-library headers. The webhook will be created for the library specified in the x-library header.

mutation CreateWebhook {
  webhooks {
    create(input: {
      name: "ERP Sync Webhook"
      description: "Syncs component updates to our ERP system"
      url: "https://api.yourcompany.com/webhooks/duro"
      events: [COMPONENT_CREATED, COMPONENT_UPDATED]
      signingSecret: "your-secret-key-min-16-chars"
      timeoutSeconds: 30
      maxRetries: 3
      isEnabled: true
    }) {
      id
      name
      url
      events
      isEnabled
      createdAt
    }
  }
}

Configuration Options

Field	Required	Description	Default
name	Yes	Unique name for this webhook (1-100 characters)	-
url	Yes	HTTPS endpoint URL (must be valid HTTPS)	-
events	Yes	Array of event types to subscribe to	-
description	No	Optional description (max 500 characters)	null
signingSecret	No	Secret for HMAC signature verification (min 16 characters if provided)	null
timeoutSeconds	No	Request timeout in seconds (5-300)	30
maxRetries	No	Maximum retry attempts on failure (0-10)	3
isEnabled	No	Whether the webhook is active	true
isArchived	Read-only	Whether the webhook has been archived (set via archive mutation)	false

List Your Webhooks

Retrieve all webhooks for the library specified in your x-library header:

query GetMyWebhooks {
  webhooks {
    findAll {
      id
      name
      description
      url
      events
      isEnabled
      isArchived
      timeoutSeconds
      maxRetries
      createdAt
      updatedAt
    }
  }
}

The findAll query returns webhooks for the library specified in the x-library header. Only active (non-archived) webhooks are returned.

Get a Specific Webhook

query GetWebhook {
  webhooks {
    findOne(id: "webhook-uuid") {
      id
      name
      description
      url
      events
      isEnabled
      isArchived
      signingSecret
      timeoutSeconds
      maxRetries
      createdAt
    }
  }
}

The findOne query returns a webhook_not_found error if the webhook has been archived.

Update a Webhook

You can update any webhook configuration field:

mutation UpdateWebhook {
  webhooks {
    update(
      id: "webhook-uuid"
      input: {
        name: "Updated Webhook Name"
        events: [COMPONENT_CREATED, COMPONENT_UPDATED, COMPONENT_DELETED]
        isEnabled: false
        maxRetries: 5
      }
    ) {
      id
      name
      events
      isEnabled
      maxRetries
    }
  }
}

Add Events to a Webhook

Add additional event subscriptions without removing existing ones:

mutation AddWebhookEvents {
  webhooks {
    addEvents(
      id: "webhook-uuid"
      input: {
        events: [COMPONENT_DELETED]
      }
    ) {
      id
      events
    }
  }
}

Remove Events from a Webhook

Remove specific event subscriptions:

mutation RemoveWebhookEvents {
  webhooks {
    removeEvents(
      id: "webhook-uuid"
      input: {
        events: [COMPONENT_DELETED]
      }
    ) {
      id
      events
    }
  }
}

Archive a Webhook

When you no longer need a webhook but want to preserve its configuration history, you can archive it instead of deleting it. Archived webhooks:

• Stop receiving events - No new event deliveries will be attempted

• Are hidden from queries - Won't appear in findAll or findOne results

• Free up the name - You can create a new webhook with the same name

• Cannot be unarchived - This action is permanent

mutation ArchiveWebhook {
  webhooks {
    archive(id: "webhook-uuid") {
      id
      name
      isArchived
    }
  }
}

Archiving a webhook is permanent and cannot be undone. If you need to temporarily stop webhook deliveries, consider using the update mutation to set isEnabled: false instead.

When to Archive vs. Disable

Action	Use Case
Disable (isEnabled: false)	Temporarily pause deliveries; webhook remains queryable and can be re-enabled
Archive	Permanently retire a webhook; frees up the name for reuse

---

Webhook Payloads

All webhook notifications follow a consistent JSON structure:

{
  "event": "components.updated",
  "eventId": "550e8400-e29b-41d4-a716-446655440000",
  "sourceId": "nats-msg-12345",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "metadata": {
    "componentId": "comp-abc123-uuid",
    "revisionValue": "1.A",
    "version": 1
  }
}

Payload Fields Explained

Field	Type	Description
event	string	The event type (e.g., components.created)
eventId	string	Unique identifier for this webhook delivery (UUID)
sourceId	string	Internal event ID for tracking and debugging
timestamp	string	ISO 8601 timestamp when the event occurred
metadata	object	Event-specific data (see below)

Component Event Metadata

For component events, the metadata object contains:

Field	Type	Description
componentId	string	UUID of the affected component
revisionValue	string	Current revision value (e.g., "1.A", "2.B")
version	number	Current version number

Example: Component Created

{
  "event": "components.created",
  "eventId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "sourceId": "nats-msg-98765",
  "timestamp": "2025-01-15T14:22:33.456Z",
  "metadata": {
    "componentId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "revisionValue": "1.A",
    "version": 1
  }
}

Example: Component Updated

{
  "event": "components.updated",
  "eventId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "sourceId": "nats-msg-54321",
  "timestamp": "2025-01-15T15:45:12.789Z",
  "metadata": {
    "componentId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "revisionValue": "1.B",
    "version": 2
  }
}

Change Order Event Metadata

Each change order event type includes different metadata fields based on the event context.

change_orders.opened

Fired when a change order transitions from draft to open status (submitted for review).

Field	Type	Description
changeOrderId	string	UUID of the change order
status	string	New status value (open)

{
  "event": "change_orders.opened",
  "eventId": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "sourceId": "nats-msg-11111",
  "timestamp": "2025-01-15T09:00:00.000Z",
  "metadata": {
    "changeOrderId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "open"
  }
}

change_orders.updated

Fired when change order details are modified (name, description, etc.) without triggering a semantic event like opened or resolution.

Field	Type	Description
changeOrderId	string	UUID of the change order

{
  "event": "change_orders.updated",
  "eventId": "d4e5f6a7-b8c9-0123-def0-456789012345",
  "sourceId": "nats-msg-22222",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "metadata": {
    "changeOrderId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

change_orders.deleted

Fired when a change order is archived.

Field	Type	Description
changeOrderId	string	UUID of the change order

{
  "event": "change_orders.deleted",
  "eventId": "e5f6a7b8-c9d0-1234-ef01-567890123456",
  "sourceId": "nats-msg-33333",
  "timestamp": "2025-01-15T11:00:00.000Z",
  "metadata": {
    "changeOrderId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

change_orders.stage_transition

Fired when a change order moves between workflow stages.

Field	Type	Description
changeOrderId	string	UUID of the change order
previousStageId	string	UUID of the previous stage (omitted if starting workflow)
newStageId	string	UUID of the new stage (omitted if resolved/completed)
transitionReason	string	Reason for the transition (e.g., stage_approved, stage_rejected)

{
  "event": "change_orders.stage_transition",
  "eventId": "f6a7b8c9-d0e1-2345-f012-678901234567",
  "sourceId": "nats-msg-44444",
  "timestamp": "2025-01-15T12:00:00.000Z",
  "metadata": {
    "changeOrderId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "previousStageId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "newStageId": "c3d4e5f6-a7b8-9012-cdef-345678901234",
    "transitionReason": "stage_approved"
  }
}

change_orders.stage_reviewer_decision

Fired when a reviewer makes a decision (approve/reject) on their assigned stage.

Field	Type	Description
changeOrderId	string	UUID of the change order
stageId	string	UUID of the stage being reviewed
reviewerId	string	UUID of the reviewer who made the decision
decision	string	The decision made (approved or rejected)

{
  "event": "change_orders.stage_reviewer_decision",
  "eventId": "a7b8c9d0-e1f2-3456-0123-789012345678",
  "sourceId": "nats-msg-55555",
  "timestamp": "2025-01-15T13:30:00.000Z",
  "metadata": {
    "changeOrderId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "stageId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "reviewerId": "d4e5f6a7-b8c9-0123-def0-456789012345",
    "decision": "approved"
  }
}

change_orders.resolution

Fired when a change order reaches a final resolution (approved, rejected, or withdrawn).

Field	Type	Description
changeOrderId	string	UUID of the change order
resolution	string	Final resolution (approved, rejected, or withdrawn)

{
  "event": "change_orders.resolution",
  "eventId": "b8c9d0e1-f2a3-4567-1234-890123456789",
  "sourceId": "nats-msg-66666",
  "timestamp": "2025-01-15T14:00:00.000Z",
  "metadata": {
    "changeOrderId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "resolution": "approved"
  }
}

change_orders.closed

Fired when a change order transitions into the terminal closed state after it has been resolved. This is distinct from change_orders.resolution: resolution records the decision (approved/rejected/withdrawn), while closed marks the change order moving into its final closed status. Both events fire for a given close.

Field	Type	Description
changeOrderId	string	UUID of the change order
sequentialId	number	Human-facing sequential number of the change order (e.g. 2 for CO-2)
libraryId	string	UUID of the library the change order belongs to
status	string	Always closed for this event
resolution	string	Resolution that preceded the close (approved, rejected, or withdrawn)
resolvedAt	string	ISO 8601 timestamp of when the change order was resolved
closedAt	string	ISO 8601 timestamp of when the change order was closed
closedByUserId	string	UUID of the user who closed the change order

{
  "event": "change_orders.closed",
  "eventId": "c9d0e1f2-a3b4-5678-2345-901234567890",
  "sourceId": "nats-msg-77777",
  "timestamp": "2025-01-15T14:05:00.000Z",
  "metadata": {
    "changeOrderId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "sequentialId": 2,
    "libraryId": "f1e2d3c4-b5a6-7890-abcd-ef0987654321",
    "status": "closed",
    "resolution": "approved",
    "resolvedAt": "2025-01-15T14:05:00.000Z",
    "closedAt": "2025-01-15T14:05:00.000Z",
    "closedByUserId": "9876fedc-ba98-7654-3210-fedcba987654"
  }
}

HTTP Headers

Each webhook request includes these headers:

Header	Value
Content-Type	application/json
User-Agent	Duro-Webhook-Service/1.0
X-Webhook-Signature	Versioned HMAC-SHA256 signature in the form sha256=<hex digest> (only sent when a signingSecret is configured on the webhook)

---

Signing Secrets

Every Duro webhook can carry a signing secret that lets your endpoint cryptographically verify each delivery actually came from Duro and was not modified in transit. Treat the signing secret like any other credential — it is the only thing protecting your endpoint from spoofed requests.

How Signing Works

When a webhook has a signingSecret, Duro signs every outbound delivery as follows:

1. Compute HMAC_SHA256(rawRequestBody, signingSecret) and hex-encode the digest.

2. Send the result in the X-Webhook-Signature header, prefixed with the algorithm version.

The header value uses a versioned, Stripe-style format:

X-Webhook-Signature: sha256=<hex digest>

The sha256= prefix is reserved for future algorithm upgrades — your verification code should split on = and reject any prefix it does not understand rather than assume a bare hex digest.

The signature is computed over the exact bytes of the request body that Duro sent. Re-serializing the JSON (for example by parsing and re-stringifying it) will produce a different signature and verification will fail. Always verify against the raw body.

Providing a Signing Secret

The signingSecret field is optional on webhooks.create and webhooks.update:

• If you provide a signingSecret, Duro stores the value you provided (minimum 16 characters).

• If you omit signingSecret on create, Duro generates a cryptographically secure signing secret for you by default. You can read it back via the findOne query.

• If a webhook has no signing secret configured at all, deliveries are sent unsigned and the X-Webhook-Signature header is omitted.

Because Duro auto-generates a signing secret on create, in practice every new webhook is signed unless you have deliberately cleared the secret.

Verifying Signatures

Your endpoint should:

1. Read the raw request body bytes before any JSON parsing.

2. Read the X-Webhook-Signature header and split it into algorithm + digest on the first =.

3. Compute HMAC_SHA256(rawBody, signingSecret) and hex-encode it.

4. Compare the computed digest to the digest from the header using a timing-safe comparison.

5. Reject the request if the header is missing, the algorithm is unknown, or the digests do not match.

Verifying Signatures (Node.js)

const crypto = require('crypto');

function verifyWebhookSignature(rawBody, headerValue, secret) {
  if (!headerValue) return false;

  // Header format is "sha256=<hex digest>". Reject anything else.
  const [algorithm, providedHex] = headerValue.split('=', 2);
  if (algorithm !== 'sha256' || !providedHex) return false;

  const expectedHex = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');

  const providedBuf = Buffer.from(providedHex, 'hex');
  const expectedBuf = Buffer.from(expectedHex, 'hex');

  // timingSafeEqual throws if the buffer lengths differ, so guard first.
  if (providedBuf.length !== expectedBuf.length) return false;

  return crypto.timingSafeEqual(providedBuf, expectedBuf);
}

// Express.js middleware example. The `express.raw` parser is critical here —
// signature verification must run against the unparsed request body.
app.post('/webhooks/duro', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const rawBody = req.body; // Buffer

  if (!verifyWebhookSignature(rawBody, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  // Signature verified - safe to parse and process.
  const payload = JSON.parse(rawBody.toString('utf8'));
  // ... handle the event

  res.status(200).send('OK');
});

Verifying Signatures (Python)

import hmac
import hashlib

def verify_webhook_signature(raw_body: bytes, header_value: str, secret: str) -> bool:
    if not header_value or "=" not in header_value:
        return False

    algorithm, _, provided_hex = header_value.partition("=")
    if algorithm != "sha256" or not provided_hex:
        return False

    expected_hex = hmac.new(
        secret.encode("utf-8"),
        raw_body,
        hashlib.sha256,
    ).hexdigest()

    # compare_digest handles length mismatches safely.
    return hmac.compare_digest(provided_hex, expected_hex)

# Flask example
import os
from flask import Flask, request, abort

app = Flask(__name__)

@app.route('/webhooks/duro', methods=['POST'])
def handle_webhook():
    signature = request.headers.get('X-Webhook-Signature')

    if not verify_webhook_signature(
        request.get_data(),  # raw bytes, not request.get_json()
        signature,
        os.environ['WEBHOOK_SECRET'],
    ):
        abort(401)

    payload = request.get_json()
    # ... handle the event

    return 'OK', 200

Endpoint Hardening Checklist

• Reject unsigned requests when you expect signatures. If your webhook has a signing secret configured, treat a missing X-Webhook-Signature header as an authentication failure (401).

• Verify against the raw body. Parsing JSON before verifying will change the byte sequence and break the signature.

• Use a constant-time comparison. Use crypto.timingSafeEqual (Node) or hmac.compare_digest (Python) — never === / ==.

• Pin the algorithm. Refuse any header that does not start with sha256= so a future algorithm migration is explicit.

• Dedupe with eventId. Signature verification proves authenticity, not uniqueness — combine it with idempotent processing keyed on eventId.

Security Best Practices

• Always use HTTPS - Webhook URLs must use HTTPS (enforced by Duro)

• Verify signatures - Always validate the X-Webhook-Signature header

• Use timing-safe comparison - Prevent timing attacks when comparing signatures

• Keep secrets secure - Store your signingSecret in environment variables, never in code

• Rotate secrets periodically - Update your signing secret via webhooks.update regularly

---

Fetching Full Resource Data

After receiving a webhook notification, use the provided IDs to fetch complete resource details via GraphQL.

Fetch Component Details

query GetComponentDetails($componentId: ID!) {
  components {
    get(filter: { ids: [$componentId] }) {
      connection {
        edges {
          node {
            id
            cpn
            name
            description
            revision
            status
            category {
              name
              code
            }
            sources {
              manufacturer
              mpn
            }
            specs {
              name
              value
              unit
            }
          }
        }
      }
    }
  }
}

Fetch Change Order Details

query GetChangeOrderDetails($changeOrderId: ID!) {
  changeOrders {
    get(id: $changeOrderId) {
      id
      name
      description
      status
      resolution
      createdAt
      updatedAt
      stage {
        id
        name
        order
      }
      items {
        id
        component {
          id
          cpn
          name
        }
        action
      }
      reviewers {
        id
        user {
          id
          email
          name
        }
        decision
        decidedAt
      }
    }
  }
}

Example: Complete Webhook Handler

Here's a complete example showing how to receive a webhook and fetch the full component data:

const express = require('express');
const crypto = require('crypto');
const { GraphQLClient } = require('graphql-request');

const app = express();
const graphqlClient = new GraphQLClient('https://api.durohub.com/graphql', {
  headers: {
    'x-api-key': process.env.DURO_API_KEY,
  },
});

const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;

function verifySignature(rawBody, headerValue) {
  if (!headerValue) return false;

  const [algorithm, providedHex] = headerValue.split('=', 2);
  if (algorithm !== 'sha256' || !providedHex) return false;

  const expectedHex = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(rawBody)
    .digest('hex');

  const provided = Buffer.from(providedHex, 'hex');
  const expected = Buffer.from(expectedHex, 'hex');
  if (provided.length !== expected.length) return false;

  return crypto.timingSafeEqual(provided, expected);
}

// Use raw body for signature verification
app.post('/webhooks/duro', express.raw({ type: 'application/json' }), async (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const rawBody = req.body; // Buffer

  // Verify signature against the raw bytes Duro signed.
  if (!verifySignature(rawBody, signature)) {
    console.error('Invalid webhook signature');
    return res.status(401).send('Unauthorized');
  }

  // Acknowledge receipt immediately (respond within timeout)
  res.status(200).send('OK');

  // Process asynchronously
  const payload = JSON.parse(rawBody.toString('utf8'));
  await processWebhook(payload);
});

async function processWebhook(payload) {
  const { event, eventId, metadata } = payload;

  console.log(`Processing ${event} event (${eventId})`);

  switch (event) {
    // Component events
    case 'components.created':
    case 'components.updated':
      await handleComponentChange(metadata);
      break;
    case 'components.deleted':
      await handleComponentDeleted(metadata);
      break;

    // Change order events
    case 'change_orders.opened':
      await handleChangeOrderOpened(metadata);
      break;
    case 'change_orders.updated':
      await handleChangeOrderUpdated(metadata);
      break;
    case 'change_orders.deleted':
      await handleChangeOrderDeleted(metadata);
      break;
    case 'change_orders.stage_transition':
      await handleStageTransition(metadata);
      break;
    case 'change_orders.stage_reviewer_decision':
      await handleReviewerDecision(metadata);
      break;
    case 'change_orders.resolution':
      await handleChangeOrderResolution(metadata);
      break;
    case 'change_orders.closed':
      await handleChangeOrderClosed(metadata);
      break;

    default:
      console.log(`Unhandled event type: ${event}`);
  }
}

async function handleComponentChange(metadata) {
  const { componentId, revisionValue, version } = metadata;

  // Fetch full component details from Duro
  const query = `
    query GetComponent($id: ID!) {
      components {
        get(filter: { ids: [$id] }) {
          connection {
            edges {
              node {
                id
                cpn
                name
                description
                revision
                status
              }
            }
          }
        }
      }
    }
  `;

  const data = await graphqlClient.request(query, { id: componentId });
  const component = data.components.get.connection.edges[0]?.node;

  if (component) {
    console.log(`Component ${component.cpn} (${component.name}) was updated`);
    // Sync to your ERP, database, or other system
    await syncToExternalSystem(component);
  }
}

async function handleComponentDeleted(metadata) {
  const { componentId } = metadata;
  console.log(`Component ${componentId} was deleted`);
  // Handle deletion in your external systems
  await removeFromExternalSystem(componentId);
}

app.listen(3000, () => {
  console.log('Webhook server listening on port 3000');
});

---

Retry Logic & Error Handling

Duro automatically retries failed webhook deliveries using exponential backoff.

Retry Schedule

A delivery is retried up to maxRetries times (the webhook's configured value, 0–10, default 3) after the initial attempt. Each attempt is given timeoutSeconds + 10 to respond before it counts as a timeout.

Delays grow exponentially (2× multiplier) starting at 60 seconds, capped at 5 minutes:

Retry	Delay before retry
1st retry	60 seconds
2nd retry	120 seconds (2 min)
3rd retry	240 seconds (4 min)
4th retry	300 seconds (5 min — cap)
5th–10th retry	300 seconds (5 min — cap)

With the default maxRetries: 3, a failing delivery is attempted 4 times total (1 initial + 3 retries) over roughly 7 minutes of backoff before the log is marked FAILED.

Not every failure is retried. If the webhook is disabled or archived (or its log row no longer exists), the delivery fails immediately and does not consume retries.

What Counts as Success?

• Success: HTTP status codes 200-299

• Failure: All other status codes, timeouts, or connection errors

Your Endpoint Should

1. Respond quickly - Return a 200 status code immediately, then process asynchronously

2. Handle duplicates - Use eventId for idempotency; you may receive the same event more than once

3. Log failures - Track and investigate webhook processing failures

4. Be available - Ensure your endpoint is highly available to receive webhooks

Example: Idempotent Processing

const processedEvents = new Set(); // In production, use Redis or a database

async function processWebhook(payload) {
  const { eventId, event, metadata } = payload;

  // Check if we've already processed this event
  if (processedEvents.has(eventId)) {
    console.log(`Event ${eventId} already processed, skipping`);
    return;
  }

  // Process the event
  await handleEvent(event, metadata);

  // Mark as processed
  processedEvents.add(eventId);
}

---

Monitoring Webhook Activity

Every delivery attempt is recorded as a webhook log. Use the filterLogs query to monitor delivery health, build dashboards, audit activity over a time window, or drive reprocessing workflows.

filterLogs replaces the deprecated getLogs query. getLogs returned an unpaginated array for a single webhook; filterLogs adds cursor pagination, multi-condition filtering (and / or), and the ability to query across every webhook in your library at once. getLogs will be removed in a future release — migrate to filterLogs.

The filterLogs query

filterLogs returns a Relay-style connection: a page of edges (each wrapping a WebhookLog node and its pagination cursor), a pageInfo block, and a totalCount of all logs matching your filter.

query RecentDeliveries {
  webhooks {
    filterLogs(input: {
      and: [{ webhookId: { eq: "webhook-uuid" } }]
      pagination: { first: 25, orderBy: { field: "createdAt", direction: DESC } }
    }) {
      totalCount
      pageInfo {
        hasNextPage
        endCursor
        resultsReturnedCount
      }
      edges {
        cursor
        node {
          id
          event
          status
          isAcknowledged
          responseCode
          responseTimeMs
          deliveryErrorMessage
          attemptCount
          processedState
          createdAt
        }
      }
    }
  }
}

Filter input structure

The input is a WebhookLogFilterInput:

Field	Type	Description
and	[WebhookLogFilterConditionInput!]	Conditions that must all match (logical AND)
or	[WebhookLogFilterConditionInput!]	Conditions where any may match (logical OR)
pagination	PaginationInput	Page size, cursor, and sort order

Each entry in and / or is a WebhookLogFilterConditionInput:

Condition field	Operator type	Filters on
webhookId	UUIDFilterInput	The webhook a log belongs to
createdAt	DateFilterInput	When the log row was created (event received)
updatedAt	DateFilterInput	When the log row was last modified (last delivery attempt / processing update)
isAcknowledged	BooleanFilterInput	Whether your endpoint returned a 2xx (true = delivered)
processedState	WebhookLogProcessedStateFilterInput	Your integration's processing outcome (see markProcessed)

status and event are returned on the log node but are not filterable server-side. To surface undelivered logs, filter on isAcknowledged: { eq: false } (matches PENDING and FAILED); to narrow by event type, return event and filter client-side.

Filter operators

# UUIDFilterInput — exact, set membership, or negation
{ eq: "uuid" }
{ in: ["uuid-a", "uuid-b"] }
{ neq: "uuid" }

# DateFilterInput — open-ended bounds, a single calendar day, or an inclusive range
{ after: "2026-05-01T00:00:00Z" }                 # strictly after (exclusive)
{ before: "2026-05-28T00:00:00Z" }                # strictly before (exclusive)
{ on: "2026-05-22T00:00:00-08:00" }               # the calendar day starting at this instant
{ rangeStart: "2026-05-01T00:00:00Z", rangeEnd: "2026-05-28T23:59:59Z" }  # inclusive range

# BooleanFilterInput
{ eq: true }

# WebhookLogProcessedStateFilterInput — SUCCESS | FAIL, plus null-awareness
{ eq: SUCCESS }
{ neq: FAIL }        # NOTE: also excludes rows where processedState IS NULL (see below)
{ isNull: true }     # only unprocessed logs

processedState uses standard SQL three-valued logic: neq: FAIL excludes both FAIL rows and unprocessed (null) rows. To match "anything that isn't FAIL, including not-yet-processed," combine neq: FAIL with isNull: true in an or.

Pagination

PaginationInput is cursor-based and forward-only:

Field	Type	Description
first	Int	Maximum number of logs to return in this page
after	String	Return logs after this cursor — pass the previous page's pageInfo.endCursor
orderBy	GenericOrderInput	{ field: String!, direction: ASC | DESC } — e.g. { field: "createdAt", direction: DESC }

Walk through all pages by repeating the query with after: <endCursor> until pageInfo.hasNextPage is false. hasPreviousPage is always false in v1.

The webhook log node

A WebhookLog carries three groups of fields:

Delivery (managed by Duro — did we reach your endpoint?)

Field	Type	Description
status	WebhookStatus!	PENDING, DELIVERED, FAILED (RETRYING is legacy and no longer written)
isAcknowledged	Boolean!	true once your endpoint returns a 2xx
responseCode	Float	HTTP status code returned by your endpoint
responseTimeMs	Float	Round-trip time of the delivery request
attemptCount	Float!	Number of delivery attempts made
deliveryErrorMessage	String	Last delivery error (timeout, connection error, non-2xx)
nextRetryAt	DateTime	When the next retry is scheduled, if retrying

Processing (managed by you via markProcessed)

Field	Type	Description
processedState	WebhookLogProcessedState	SUCCESS, FAIL, or null (not yet processed)
processedAt	DateTime	When you reported the processing outcome
processingErrorMessage	String	Failure reason you supplied when reporting FAIL

Identity & content

Field	Type	Description
id	ID!	Log ID — pass this to markProcessed
webhookId	ID!	The webhook that produced this log
event	String!	Event type (e.g. components.created)
payload	JSONObject!	The exact payload delivered to your endpoint
createdAt / updatedAt	DateTime!	Row timestamps

The errorMessage field is deprecated — it is an alias for deliveryErrorMessage. Use deliveryErrorMessage going forward.

Examples

Find undelivered logs across all your webhooks (anything that hasn't received a 2xx):

query UndeliveredLogs {
  webhooks {
    filterLogs(input: {
      and: [{ isAcknowledged: { eq: false } }]
      pagination: { first: 50, orderBy: { field: "createdAt", direction: DESC } }
    }) {
      totalCount
      edges {
        node {
          id
          webhookId
          event
          status
          attemptCount
          responseCode
          deliveryErrorMessage
          nextRetryAt
        }
      }
    }
  }
}

Audit a reporting window (all logs for one webhook in May 2026):

query MonthlyAudit {
  webhooks {
    filterLogs(input: {
      and: [
        { webhookId: { eq: "webhook-uuid" } }
        { createdAt: { rangeStart: "2026-05-01T00:00:00Z", rangeEnd: "2026-05-31T23:59:59Z" } }
      ]
      pagination: { first: 100, orderBy: { field: "createdAt", direction: ASC } }
    }) {
      totalCount
      pageInfo { hasNextPage endCursor }
      edges { node { id event status processedState createdAt } }
    }
  }
}

Find a backlog of unprocessed deliveries (delivered to you, but your integration hasn't reported an outcome — pairs with markProcessed):

query UnprocessedBacklog {
  webhooks {
    filterLogs(input: {
      and: [
        { isAcknowledged: { eq: true } }
        { processedState: { isNull: true } }
      ]
      pagination: { first: 50, orderBy: { field: "createdAt", direction: ASC } }
    }) {
      totalCount
      edges { node { id event payload createdAt } }
    }
  }
}

Find deliveries your integration failed to process (for reprocessing / dead-letter handling):

query FailedProcessing {
  webhooks {
    filterLogs(input: {
      and: [{ processedState: { eq: FAIL } }]
      pagination: { first: 50, orderBy: { field: "updatedAt", direction: DESC } }
    }) {
      edges { node { id event processingErrorMessage processedAt payload } }
    }
  }
}

Example: Monitoring Script

// Page through every undelivered log across your webhooks.
async function findUndeliveredLogs() {
  const query = `
    query Undelivered($after: String) {
      webhooks {
        filterLogs(input: {
          and: [{ isAcknowledged: { eq: false } }]
          pagination: { first: 100, after: $after, orderBy: { field: "createdAt", direction: DESC } }
        }) {
          totalCount
          pageInfo { hasNextPage endCursor }
          edges {
            node { id webhookId event status attemptCount deliveryErrorMessage }
          }
        }
      }
    }
  `;

  const undelivered = [];
  let after = null;

  // Walk forward until there are no more pages.
  do {
    const data = await graphqlClient.request(query, { after });
    const { edges, pageInfo } = data.webhooks.filterLogs;
    undelivered.push(...edges.map((e) => e.node));
    after = pageInfo.hasNextPage ? pageInfo.endCursor : null;
  } while (after);

  if (undelivered.length > 0) {
    console.warn(`${undelivered.length} webhook deliveries have not been acknowledged:`);
    undelivered.forEach((log) => {
      console.warn(`  - [${log.webhookId}] ${log.event}: ${log.deliveryErrorMessage ?? 'pending'} (attempt ${log.attemptCount})`);
    });
  }

  return undelivered;
}

---

Tracking Processing Outcomes with markProcessed

A log's status (DELIVERED / FAILED) reflects whether Duro successfully delivered the HTTP POST to your endpoint and received a 2xx. It says nothing about whether your integration successfully processed the event afterward — your ERP sync might reject the part, your job queue might fail, your downstream API might be down.

markProcessed lets you record that application-side outcome back onto the webhook log as a processedState (SUCCESS or FAIL), with an optional failure reason.

markProcessed is optional — webhooks work exactly the same whether or not you call it. Its value is that it pairs with filterLogs: once you report processing outcomes, you can query for unprocessed or failed-processing logs to build reconciliation, retry, and dead-letter workflows entirely off Duro's log store — no separate tracking database required.

Reporting a successful outcome

mutation MarkSuccess {
  webhooks {
    markProcessed(input: {
      id: "webhook-log-uuid"
      state: SUCCESS
    }) {
      id
      processedState
      processedAt
    }
  }
}

Reporting a failure

Supply a processingErrorMessage so the reason is visible in later filterLogs queries:

mutation MarkFailure {
  webhooks {
    markProcessed(input: {
      id: "webhook-log-uuid"
      state: FAIL
      processingErrorMessage: "ERP rejected part CMP-001234: duplicate MPN"
    }) {
      id
      processedState
      processingErrorMessage
      processedAt
    }
  }
}

Input fields (WebhookMarkProcessedInput)

Field	Required	Description
id	Yes	The WebhookLog id to mark
state	Yes	SUCCESS or FAIL
processingErrorMessage	No	Failure reason when state: FAIL. Persisted on the log; capped at 4000 characters — truncate stack traces client-side

Delivery status vs. processed state

These are two independent dimensions of a single log:

	Owned by	Field(s)	Question it answers
Delivery	Duro	status, isAcknowledged, responseCode	Did Duro reach your endpoint and get a 2xx?
Processing	You (markProcessed)	processedState, processedAt, processingErrorMessage	Did your integration successfully handle the event?

A log can be DELIVERED (Duro's POST succeeded) yet processedState: FAIL (your ERP sync threw) — that combination is exactly what reconciliation workflows look for.

Use cases

• Reconciliation backlog — report SUCCESS after each event is fully handled, then periodically query filterLogs(processedState: { isNull: true }, isAcknowledged: { eq: true }) to find delivered-but-not-yet-processed events your system may have dropped (a crash between receiving and processing).

• Reprocessing / dead-letter — on a processing failure, call markProcessed(state: FAIL, processingErrorMessage: ...), then run a retry job over filterLogs(processedState: { eq: FAIL }).

• Auditing & SLA — processedAt gives an authoritative "when did the integration finish" timestamp alongside Duro's delivery timestamps, without standing up your own tracking store.

Example: receive → process → report

app.post('/webhooks/duro', express.raw({ type: 'application/json' }), async (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const rawBody = req.body;

  if (!verifySignature(rawBody, signature)) {
    return res.status(401).send('Unauthorized');
  }

  // Acknowledge delivery immediately (this drives Duro's DELIVERED status).
  res.status(200).send('OK');

  const payload = JSON.parse(rawBody.toString('utf8'));

  // The webhook log id is not in the payload — resolve it via filterLogs using
  // the payload's sourceId, or track your own mapping. Here we assume logId is
  // resolved out-of-band.
  const logId = await resolveLogId(payload.sourceId);

  try {
    await processWebhook(payload);
    await markProcessed(logId, 'SUCCESS');
  } catch (err) {
    // Report the application-side failure so it surfaces in filterLogs.
    await markProcessed(logId, 'FAIL', err.message);
  }
});

async function markProcessed(id, state, processingErrorMessage) {
  const mutation = `
    mutation MarkProcessed($input: WebhookMarkProcessedInput!) {
      webhooks { markProcessed(input: $input) { id processedState } }
    }
  `;
  const input = { id, state };
  if (state === 'FAIL' && processingErrorMessage) {
    input.processingErrorMessage = processingErrorMessage.slice(0, 4000);
  }
  await graphqlClient.request(mutation, { input });
}

---

Common Use Cases

ERP Integration

Sync component and BOM changes to your ERP system in real-time:

async function syncToERP(component) {
  // Map Duro fields to your ERP schema
  const erpItem = {
    partNumber: component.cpn,
    description: component.name,
    revision: component.revision,
    status: mapStatusToERP(component.status),
  };

  // Upsert to ERP
  await erpClient.upsertItem(erpItem);
  console.log(`Synced ${component.cpn} to ERP`);
}

app.post('/webhooks/duro', async (req, res) => {
  // ... verification code ...

  res.status(200).send('OK');

  const { event, metadata } = req.body;

  if (event === 'components.created' || event === 'components.updated') {
    const component = await fetchComponentFromDuro(metadata.componentId);
    await syncToERP(component);
  }
});

Slack Notifications

Alert your team about important component changes:

const { WebClient } = require('@slack/web-api');
const slack = new WebClient(process.env.SLACK_TOKEN);

async function notifySlack(event, component) {
  const emoji = event === 'components.created' ? ':heavy_plus_sign:' : ':pencil2:';
  const action = event === 'components.created' ? 'created' : 'updated';

  await slack.chat.postMessage({
    channel: '#engineering-updates',
    text: `${emoji} Component *${component.cpn}* was ${action}`,
    blocks: [
      {
        type: 'section',
        text: {
          type: 'mrkdwn',
          text: `${emoji} Component *${component.cpn}* was ${action}`,
        },
      },
      {
        type: 'section',
        fields: [
          { type: 'mrkdwn', text: `*Name:*\n${component.name}` },
          { type: 'mrkdwn', text: `*Revision:*\n${component.revision}` },
          { type: 'mrkdwn', text: `*Status:*\n${component.status}` },
        ],
      },
    ],
  });
}

Audit Logging

Maintain a detailed audit trail of all changes:

async function logToAuditSystem(payload, component) {
  const auditEntry = {
    timestamp: payload.timestamp,
    eventId: payload.eventId,
    eventType: payload.event,
    resourceType: 'component',
    resourceId: payload.metadata.componentId,
    resourceCpn: component?.cpn,
    revision: payload.metadata.revisionValue,
    version: payload.metadata.version,
  };

  await auditDatabase.insert('webhook_audit_log', auditEntry);
  console.log(`Audit log created for ${payload.eventId}`);
}

Change Order Workflow Tracking

Monitor change order progress and sync approval status to external systems:

async function handleChangeOrderEvents(payload) {
  const { event, metadata, timestamp } = payload;

  switch (event) {
    case 'change_orders.opened':
      // Change order submitted for review
      await notifyReviewers(metadata.changeOrderId);
      await updateProjectManagementSystem(metadata.changeOrderId, 'in_review');
      break;

    case 'change_orders.stage_transition':
      // Track workflow progress
      console.log(`CO ${metadata.changeOrderId} moved to stage ${metadata.newStageId}`);
      await syncWorkflowStatus(metadata);
      break;

    case 'change_orders.stage_reviewer_decision':
      // Individual reviewer decision
      const action = metadata.decision === 'approved' ? 'approved' : 'rejected';
      await logReviewerAction(metadata.changeOrderId, metadata.reviewerId, action);
      break;

    case 'change_orders.resolution':
      // Final resolution - approved, rejected, or withdrawn
      if (metadata.resolution === 'approved') {
        await triggerPostApprovalWorkflow(metadata.changeOrderId);
        await notifyStakeholders(metadata.changeOrderId, 'Change order approved');
      } else if (metadata.resolution === 'rejected') {
        await notifyOwner(metadata.changeOrderId, 'Change order rejected');
      }
      break;
  }
}

async function triggerPostApprovalWorkflow(changeOrderId) {
  // Fetch full change order details
  const changeOrder = await fetchChangeOrderFromDuro(changeOrderId);

  // Sync approved components to ERP
  for (const item of changeOrder.items) {
    if (item.action === 'release') {
      await syncComponentToERP(item.component);
    }
  }

  console.log(`Post-approval workflow completed for CO ${changeOrderId}`);
}

---

Troubleshooting

Common Issues

Webhook not receiving events

1. Check if webhook is enabled - Query the webhook and verify isEnabled: true

2. Verify event subscriptions - Ensure the correct events are in the events array

3. Check your endpoint - Verify your URL is accessible from the internet

4. Review logs - Use the filterLogs query to see delivery attempts and errors (filter on webhookId and isAcknowledged: { eq: false } to surface undelivered events)

Signature verification failing

1. Check the secret - Ensure you're using the exact same signingSecret you configured on the webhook

2. Use the raw body - Signature is computed over the raw request bytes, not a re-serialized JSON object. Any middleware that parses or rewrites the body before verification will break the signature

3. Strip the sha256= prefix - The header value is sha256=<hex>, not a bare hex digest. Split on the first = and compare only the hex portion

4. Match digest lengths first - crypto.timingSafeEqual throws when buffers differ in length; guard with a length check before comparing

5. Check encoding - Ensure UTF-8 encoding throughout

Missing webhook deliveries

1. Check retry status - Some deliveries may be queued for retry

2. Verify library scope - Webhooks only fire for events in their configured library

3. Check component filters - Events fire for all components in the library

Testing Your Webhook Endpoint

Before configuring a production webhook, test your endpoint:

# Send a test payload to your endpoint
curl -X POST https://your-endpoint.com/webhooks/duro \
  -H "Content-Type: application/json" \
  -H "User-Agent: Duro-Webhook-Service/1.0" \
  -d '{
    "event": "components.updated",
    "eventId": "test-event-id",
    "sourceId": "test-source-id",
    "timestamp": "2025-01-15T10:30:00.000Z",
    "metadata": {
      "componentId": "test-component-id",
      "revisionValue": "1.A",
      "version": 1
    }
  }'

---

Migrating from v1 to v2

v1 webhook payloads included complete resource data. v2 uses a "Ping then Pull" pattern—you receive minimal metadata and fetch full details via GraphQL when needed.

Event Mapping

v1 Event	v2 Event	Notes
co.Submitted	CHANGE_ORDER_OPENED
co.Approved	CHANGE_ORDER_RESOLUTION	Check metadata.resolution === 'approved'
co.Rejected	CHANGE_ORDER_RESOLUTION	Check metadata.resolution === 'rejected'

Example: Change Order Approved

v1 payload (complete data embedded):

{
  "_id": "507f1f77bcf86cd799439011",
  "con": "ECO-001",
  "name": "Update PCB Design",
  "description": "Replace capacitors with higher rated components",
  "eventType": "co.Approved",
  "resolution": "APPROVED",
  "status": "CLOSED",
  "type": "ECO",
  "created": "2025-01-15T10:00:00.000Z",
  "creator": "507f1f77bcf86cd799439012",
  "firstName": "John",
  "lastName": "Doe",
  "email": "[e-mail]",
  "approvalType": "STANDARD",
  "lastModified": "2025-01-15T14:00:00.000Z",
  "approverList": [
    {
      "user": "507f1f77bcf86cd799439013",
      "firstName": "Jane",
      "lastName": "Smith",
      "email": "[e-mail]",
      "action": "APPROVED",
      "performedAt": "2025-01-15T14:00:00.000Z"
    }
  ],
  "children": {
    "components": [
      { "_id": "507f1f77bcf86cd799439014", "cpn": "CMP-001234", "name": "Capacitor 100uF" }
    ],
    "products": []
  },
  "history": [
    { "action": "APPROVED", "user": "507f1f77bcf86cd799439013", "created": "2025-01-15T14:00:00.000Z" }
  ]
}

v2 payload (metadata only):

{
  "event": "change_orders.resolution",
  "eventId": "b8c9d0e1-f2a3-4567-1234-890123456789",
  "sourceId": "nats-msg-66666",
  "timestamp": "2025-01-15T14:00:00.000Z",
  "metadata": {
    "changeOrderId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "resolution": "approved"
  }
}

What's Not Included in v2

The following v1 fields are not in the v2 webhook payload. Use the GraphQL API to retrieve this data:

v1 Field	How to Get in v2
con, name, description	Query changeOrders.get()
status, type, resolution	Query changeOrders.get()
creator, firstName, lastName, email	Query changeOrders.get() with createdBy field
approverList	Query changeOrders.get() with reviewers field
children.components, children.products	Query changeOrders.get() with items field
history	Query change order audit log
created, lastModified	Query changeOrders.get() with createdAt, updatedAt

Updating Your Handler

v1:

if (payload.eventType === 'co.Approved') {
  for (const component of payload.children.components) {
    releaseToERP(component.cpn);
  }
}

v2:

if (payload.event === 'change_orders.resolution' && payload.metadata.resolution === 'approved') {
  const changeOrder = await fetchChangeOrder(payload.metadata.changeOrderId);
  for (const item of changeOrder.items) {
    releaseToERP(item.component.cpn);
  }
}

See Fetch Change Order Details for the GraphQL query and Signing Secrets for signature verification.

---

Next Steps

• Review Authentication for securing your API requests

• Explore Searching and Filtering for advanced component queries

• Learn about Change Orders to understand change order workflows

• Check out Error Handling for robust integration patterns