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

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"
  }
}

HTTP Headers

Each webhook request includes these headers:

Header	Value
Content-Type	application/json
User-Agent	Duro-Webhook-Service/1.0
X-Webhook-Signature	HMAC-SHA256 signature (only if signingSecret is configured)

---

Security

Webhook Signatures

If you configure a signingSecret for your webhook, each request will include an X-Webhook-Signature header containing an HMAC-SHA256 signature of the payload. Always verify this signature to ensure the request came from Duro.

Verifying Signatures (Node.js)

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  // payload should be the raw request body as a string
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  // Use timing-safe comparison to prevent timing attacks
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

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

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

  // Signature verified - process the webhook
  const payload = JSON.parse(rawBody);
  // ... handle the event

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

Verifying Signatures (Python)

import hmac
import hashlib

def verify_webhook_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected_signature = hmac.new(
        secret.encode('utf-8'),
        payload,
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(signature, expected_signature)

# Flask example
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 signature or not verify_webhook_signature(
        request.data,
        signature,
        os.environ['WEBHOOK_SECRET']
    ):
        abort(401)

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

    return 'OK', 200

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 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(payload, signature) {
  if (!signature) return false;
  const expected = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(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.toString();

  // Verify signature
  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);
  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;

    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

When a webhook delivery fails, Duro will retry with the following delays:

Attempt	Delay After Failure
1st retry	1 second
2nd retry	2 seconds
3rd retry	4 seconds
4th retry	8 seconds
5th retry	16 seconds
6th retry	32 seconds
7th retry	64 seconds
8th retry	128 seconds
9th retry	256 seconds
10th retry	300 seconds (5 min max)

The retry schedule follows exponential backoff (2x multiplier) with a maximum delay of 5 minutes.

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

Query your webhook logs to monitor delivery status and troubleshoot issues:

query GetWebhookLogs {
  webhooks {
    getLogs(webhookId: "webhook-uuid") {
      id
      event
      payload
      status
      responseCode
      responseTimeMs
      errorMessage
      attemptCount
      nextRetryAt
      isAcknowledged
      createdAt
    }
  }
}

Log Status Values

Status	Description
PENDING	Delivery in progress
DELIVERED	Successfully delivered (2xx response)
RETRYING	Failed, waiting for retry
FAILED	All retry attempts exhausted

Example: Monitoring Script

async function checkWebhookHealth(webhookId) {
  const query = `
    query GetLogs($webhookId: String!) {
      webhooks {
        getLogs(webhookId: $webhookId) {
          id
          event
          status
          responseCode
          attemptCount
          errorMessage
          createdAt
        }
      }
    }
  `;

  const data = await graphqlClient.request(query, { webhookId });
  const logs = data.webhooks.getLogs;

  const failed = logs.filter(log => log.status === 'FAILED');
  const retrying = logs.filter(log => log.status === 'RETRYING');

  if (failed.length > 0) {
    console.warn(`${failed.length} webhook deliveries failed!`);
    failed.forEach(log => {
      console.warn(`  - ${log.event}: ${log.errorMessage}`);
    });
  }

  if (retrying.length > 0) {
    console.log(`${retrying.length} webhooks pending retry`);
  }
}

---

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 getLogs query to see delivery attempts and errors

Signature verification failing

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

2. Use raw body - Signature is computed on the raw JSON string, not a parsed object

3. 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": "[email protected]",
  "approvalType": "STANDARD",
  "lastModified": "2025-01-15T14:00:00.000Z",
  "approverList": [
    {
      "user": "507f1f77bcf86cd799439013",
      "firstName": "Jane",
      "lastName": "Smith",
      "email": "[email protected]",
      "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 Security 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