Field NationDeveloper Platform
Field NationDeveloper Platform
IntroductionQuickstartAPI Playground

Documentation

Webhook EventsPayload StructureDelivery MechanicsWebhook Lifecycle

Support

Migration Guide
Core Concepts

Webhook Lifecycle

Understanding webhook states (active, inactive, archived), transitions, history tracking, and change auditing.

Webhook States

Loading diagram...

Active State

Definition: Webhook is fully operational and receiving event notifications.

Characteristics

  • ✅ Events are queued for delivery
  • ✅ Delivery attempts made according to retry policy
  • ✅ Delivery logs generated
  • ✅ Can be modified (events, URL, etc.)
  • ✅ Can transition to inactive or archived

When to Use

  • Production webhooks: Actively processing events
  • Monitoring: Need real-time updates
  • Integration running: System operational

Creating Active Webhook

curl -X POST https://api-sandbox.fndev.net/api/v1/webhooks \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-endpoint.com/webhooks",
    "method": "post",
    "status": "active",
    "events": ["workorder.status.published"]
  }'
  1. Navigate to Webhooks Dashboard
  2. Click "Create New"
  3. Fill in configuration
  4. Set Status to "Active"
  5. Click "Create"

Inactive State

Definition: Webhook is temporarily paused and not receiving events.

Characteristics

  • ❌ Events are not queued or delivered
  • ❌ No delivery attempts made
  • ✅ Configuration preserved
  • ✅ Historical delivery logs remain accessible
  • ✅ Can be modified
  • ✅ Can transition to active or archived

When to Use

  • Maintenance: Endpoint undergoing updates
  • Temporary issues: Fixing integration problems
  • Testing: Paused during development
  • Rate limiting: Temporarily reduce load

Common Use Cases

Maintenance Window

// Pause webhook during deployment
await fetch('https://api-sandbox.fndev.net/api/v1/webhooks/wh_abc123', {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ status: 'inactive' })
});

// Perform deployment...

// Reactivate after deployment
await fetch('https://api-sandbox.fndev.net/api/v1/webhooks/wh_abc123', {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ status: 'active' })
});

Incident Response

# Quickly pause webhook during incident
curl -X PUT https://api-sandbox.fndev.net/api/v1/webhooks/wh_abc123 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "inactive"}'

Pausing vs Deleting

Best Practice: Use inactive for temporary pauses instead of deleting and recreating. This preserves:

  • Webhook ID and secret
  • Delivery history
  • Configuration settings
  • Change history

Archived State

Definition: Webhook is permanently deactivated and read-only.

Characteristics

  • ❌ Events are not delivered
  • ❌ Cannot be reactivated (permanent)
  • ❌ Cannot be modified
  • ✅ Configuration visible (read-only)
  • ✅ Historical delivery logs preserved
  • ✅ Appears in webhook list with "archived" badge

When to Use

  • Decommissioned integrations: Project ended
  • Replaced webhooks: New version created
  • Historical record: Keep audit trail
  • Cleanup: Organize active webhooks

Archiving a Webhook

curl -X PUT https://api-sandbox.fndev.net/api/v1/webhooks/wh_abc123 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "archived"
  }'

Irreversible: Once archived, a webhook cannot be reactivated. Create a new webhook if needed.

  1. Navigate to webhook details
  2. Click "Settings"
  3. Change Status to "Archived"
  4. Confirm action

Irreversible: Cannot undo archival. Consider using "Inactive" for temporary pauses.

Archive vs Delete

ActionConfigurationDelivery LogsReversible
ArchivePreserved (read-only)PreservedNo
DeleteRemovedPreservedNo

Recommendation: Archive webhooks instead of deleting to maintain audit trails.

State Transitions

Valid Transitions

active ⟷ inactive    ✅ Bidirectional
active → archived    ✅ One-way
inactive → archived  ✅ One-way
archived → active    ❌ Not allowed
archived → inactive  ❌ Not allowed

Transition API

# Active → Inactive
curl -X PUT https://api-sandbox.fndev.net/api/v1/webhooks/wh_abc123 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "inactive"}'

# Inactive → Active
curl -X PUT https://api-sandbox.fndev.net/api/v1/webhooks/wh_abc123 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "active"}'

# Any → Archived (permanent)
curl -X PUT https://api-sandbox.fndev.net/api/v1/webhooks/wh_abc123 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "archived"}'

Automatic State Changes

Field Nation may automatically change webhook state under certain conditions:

Auto-Deactivation

Trigger: 7 consecutive days of failed deliveries

Action: active → inactive

Notification: Email sent to notificationEmail (if configured)

Reason: Prevent infinite retry loops on broken endpoints

Recovery:

# Fix endpoint issues first, then reactivate
curl -X PUT https://api-sandbox.fndev.net/api/v1/webhooks/wh_abc123 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "active"}'

Important: Fix underlying issues before reactivating. Repeated auto-deactivations may result in webhook being permanently archived.

Change History & Audit Trail

Every webhook modification is tracked in a comprehensive change history.

Tracked Changes

  • Status transitions (active ⟷ inactive, → archived)
  • URL modifications
  • Event subscriptions (added/removed)
  • HTTP method changes
  • Secret regeneration
  • Custom header updates
  • Notification email changes

Accessing Change History

Via API

curl -X GET "https://api-sandbox.fndev.net/api/v1/webhooks/wh_abc123/history" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "metadata": {
    "timestamp": "2025-01-15T11:00:00Z",
    "count": 5,
    "total": 5
  },
  "result": [
    {
      "id": 123,
      "userId": 456,
      "action": "status_changed",
      "changes": {
        "status": {
          "from": "active",
          "to": "inactive"
        }
      },
      "createdAt": "2025-01-15T10:45:00Z",
      "updatedAt": "2025-01-15T10:45:00Z"
    },
    {
      "id": 122,
      "userId": 456,
      "action": "events_updated",
      "changes": {
        "events": {
          "added": ["workorder.status.approved"],
          "removed": ["workorder.status.draft"]
        }
      },
      "createdAt": "2025-01-15T09:30:00Z",
      "updatedAt": "2025-01-15T09:30:00Z"
    },
    {
      "id": 121,
      "userId": 456,
      "action": "url_changed",
      "changes": {
        "url": {
          "from": "https://old-endpoint.com/webhook",
          "to": "https://new-endpoint.com/webhooks"
        }
      },
      "createdAt": "2025-01-14T15:20:00Z",
      "updatedAt": "2025-01-14T15:20:00Z"
    }
  ]
}

Via Web UI

  1. Navigate to Webhooks Dashboard
  2. Click on webhook
  3. Go to "History" tab
  4. View chronological list of changes

Webhook Change History

Filter History

# Filter by user
curl -X GET "https://api-sandbox.fndev.net/api/v1/webhooks/wh_abc123/history?userId=456" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Filter by action
curl -X GET "https://api-sandbox.fndev.net/api/v1/webhooks/wh_abc123/history?search=status_changed" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Lifecycle Management Best Practices

Use Descriptive Notification Emails

Configure an email to receive alerts:

{
  "notificationEmail": "webhook-alerts+production@example.com"
}

Benefits:

  • Receive auto-deactivation warnings
  • Track delivery failures
  • Monitor webhook health

Tag Webhooks for Organization

Use naming conventions or custom headers to identify webhooks:

// Create webhook with identifier in URL or custom headers
{
  "url": "https://your-endpoint.com/webhooks/production",
  "webhookAttribute": {
    "header": {
      "X-Webhook-Environment": "production",
      "X-Webhook-Owner": "team-integrations"
    }
  }
}

Monitor State Changes

Track webhook state changes in your monitoring system:

async function checkWebhookHealth() {
  const webhooks = await fetch(
    'https://api-sandbox.fndev.net/api/v1/webhooks',
    {
      headers: { 'Authorization': `Bearer ${accessToken}` }
    }
  ).then(r => r.json());

  const inactive = webhooks.result.filter(w => w.status === 'inactive');

  if (inactive.length > 0) {
    await alertTeam(`${inactive.length} webhooks are inactive`, inactive);
  }
}

Implement Graceful Deprecation

When replacing webhooks:

Create New Webhook

Create the new webhook with updated configuration:

curl -X POST https://api-sandbox.fndev.net/api/v1/webhooks \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://new-endpoint.com/webhooks",
    "method": "post",
    "status": "active",
    "events": ["workorder.status.published"]
  }'

Test New Webhook

Verify new webhook works correctly before deactivating old one.

Pause Old Webhook

Set old webhook to inactive:

curl -X PUT https://api-sandbox.fndev.net/api/v1/webhooks/wh_old123 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "inactive"}'

Monitor for Issues

Watch for missing events or processing errors.

Archive Old Webhook

Once confident, archive the old webhook:

curl -X PUT https://api-sandbox.fndev.net/api/v1/webhooks/wh_old123 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "archived"}'

Viewing Webhook Status

List Webhooks by Status

curl -X GET "https://api-sandbox.fndev.net/api/v1/webhooks?status=active" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
curl -X GET "https://api-sandbox.fndev.net/api/v1/webhooks?status=inactive" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
curl -X GET "https://api-sandbox.fndev.net/api/v1/webhooks?status=archived" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
curl -X GET "https://api-sandbox.fndev.net/api/v1/webhooks" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Get Specific Webhook Status

curl -X GET https://api-sandbox.fndev.net/api/v1/webhooks/wh_abc123 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "metadata": {
    "timestamp": "2025-01-15T11:00:00Z"
  },
  "result": {
    "id": 123,
    "webhookId": "wh_abc123",
    "url": "https://your-endpoint.com/webhooks",
    "method": "post",
    "status": "active",
    "events": ["workorder.status.published", "workorder.status.assigned"],
    "createdAt": "2025-01-10T10:00:00Z",
    "updatedAt": "2025-01-15T10:45:00Z"
  }
}

Lifecycle Event Flow

Loading diagram...

Last updated on

Delivery Mechanics

How webhooks are delivered, retry logic with exponential backoff, message queuing, and automatic deactivation policies.

Creating Webhooks

Step-by-step guide to creating and configuring webhooks using the Web UI or REST API with examples for both methods.

On this page

Webhook States
Active State
Characteristics
When to Use
Creating Active Webhook
Inactive State
Characteristics
When to Use
Common Use Cases
Maintenance Window
Incident Response
Pausing vs Deleting
Archived State
Characteristics
When to Use
Archiving a Webhook
Archive vs Delete
State Transitions
Valid Transitions
Transition API
Automatic State Changes
Auto-Deactivation
Change History & Audit Trail
Tracked Changes
Accessing Change History
Via API
Via Web UI
Filter History
Lifecycle Management Best Practices
Use Descriptive Notification Emails
Tag Webhooks for Organization
Monitor State Changes
Implement Graceful Deprecation
Create New Webhook
Test New Webhook
Pause Old Webhook
Monitor for Issues
Archive Old Webhook
Viewing Webhook Status
List Webhooks by Status
Get Specific Webhook Status
Lifecycle Event Flow