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 (Coming Soon)

Change order webhook events are defined but not yet implemented. The event names and payload structures below represent the planned implementation. We'll update this documentation when these events become available.

GraphQL Enum	Payload Value	Description
CHANGE_ORDER_OPENED	change_orders.opened	A new change order was created
CHANGE_ORDER_UPDATED	change_orders.updated	Change order details were modified
CHANGE_ORDER_DELETED	change_orders.deleted	A change order was removed
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

---

Setting Up Webhooks

Create a Webhook

To create a webhook, you'll need:

• A libraryId - the library you want to monitor

• A url - your HTTPS endpoint that will receive notifications

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

mutation CreateWebhook {
  webhooks {
    create(input: {
      libraryId: "your-library-uuid"
      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
libraryId	Yes	UUID of the library to monitor	-
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 one or more libraries:

query GetMyWebhooks {
  webhooks {
    findAll(input: {
      libraryIds: ["library-uuid-1", "library-uuid-2"]
    }) {
      id
      name
      description
      url
      events
      isEnabled
      isArchived
      timeoutSeconds
      maxRetries
      createdAt
      updatedAt
    }
  }
}

The findAll query only returns active (non-archived) webhooks. Archived webhooks are excluded from results.

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

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

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) {
    case 'components.created':
    case 'components.updated':
      await handleComponentChange(metadata);
      break;
    case 'components.deleted':
      await handleComponentDeleted(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}`);
}

---

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

---

Next Steps

• Review Authentication for securing your API requests

• Explore Searching and Filtering for advanced component queries

• Learn about Change Orders to prepare for change order webhooks

• Check out Error Handling for robust integration patterns