Skip to content

Webhooks

IP Fabric can notify external services when snapshot events occur. This plugin exposes a webhook endpoint on every Sync that, when called by IP Fabric after a successful discovery or load, automatically queues both a source sync (to pull the new snapshot metadata) and an ingestion sync — with no human intervention required.

How It Works

IP Fabric (discover/load completed)
        │
        │  POST /api/plugins/ipfabric/sync/<pk>/webhook/
        │  X-IPF-Signature: <hmac-sha256>
        ▼
  NetBox webhook endpoint
        │  1. Verify HMAC-SHA256 signature
        │  2. Filter event  (action, status, test flag)
        │  3. enqueue_sync_job(adhoc=True,
        │                      user=<configured user>,
        │                      pending_snapshot_id=<snapshot UUID>)
        ▼
  RQ Worker
        │  ① Source sync  – pulls latest snapshot list from IP Fabric
        │  ② Ingestion sync – resolves the pending snapshot, then ingests
        ▼
  NetBox data updated

Snapshot timing

The snapshot UUID received in the webhook will usually not exist in NetBox yet when the webhook arrives. The source sync that is queued first takes care of pulling it in; the ingestion sync then resolves the ID and proceeds. If the snapshot is still absent after the source sync (e.g. the source sync failed), the ingestion job is terminated immediately with an error.

Prerequisites

  • The NetBox instance must be reachable from IP Fabric over HTTPS.
  • A dedicated NetBox user should be created for webhook-triggered jobs (e.g. ipfabric-bot) with the ipfabric_netbox.sync_ipfabricsync permission.
  • One Sync per IP Fabric webhook — each webhook carries its own HMAC secret.

Configuration

1 — Add webhook secrets to configuration.py

Open the NetBox configuration file and add (or extend) PLUGINS_CONFIG:

PLUGINS_CONFIG = {
    "ipfabric_netbox": {
        # Maps IPFabricSync primary-key (integer) to its HMAC secret and the
        # NetBox username that will own the queued jobs.
        "webhook_secrets": {
            7:  {"secret": "change-me-sync-7",  "username": "ipfabric-bot"},
            12: {"secret": "change-me-sync-12", "username": "ipfabric-bot"},
        },
    },
}
Key Type Description
secret str The HMAC secret you will obtain from IP Fabric UI.
username str NetBox username whose identity the sync job runs under.

2 — Restart NetBox

sudo systemctl restart netbox netbox-rq

3 — Create the webhook in IP Fabric

  1. In IP Fabric navigate to Settings → Integration → Webhooks → [ + Add ].

  2. Fill in the form fields:

    Field Value
    Active Enabled
    Name Any descriptive label, e.g. NetBox Sync
    URL https://<netbox-host>/api/plugins/ipfabric/sync/<sync-pk>/webhook/

    Replace <sync-pk> with the integer primary key of your IPFabricSync (visible in the NetBox URL when viewing the sync detail page).

  3. Under Which events would you like to trigger this webhook? enable Snapshot only — leave Intent verification unchecked.

  4. Click Save.

IP Fabric Webhook Configuration

Verify with the Test button

Click Test in IP Fabric after saving. The plugin will receive the event, detect test: true, and return 200 Ignored without queuing any job. A 200 response in the Recent deliveries panel confirms the secret and URL are correct.

Payload Filtering

The endpoint silently returns 200 (no job queued) for any event that does not match all of the following conditions:

Field Required value If absent / wrong
action "discover" or "load" 200 — ignored
status "completed" 200 — ignored
test absent or false 200 — ignored
snapshot object present and contains id 400 — bad request

All other action/status combinations (clone, delete, download, unload, started, failed, resumed, stopped, …) are ignored with 200.

Security — HMAC-SHA256 Verification

IP Fabric computes an HMAC-SHA256 digest of the raw request body using the secret configured in its UI and sends the hex digest in the X-IPF-Signature HTTP header.

Requests with a missing or invalid signature are rejected with 401. Because the secret is never part of the URL it does not appear in access logs.

Response Codes

Code Meaning
202 Event matched; source sync + ingestion sync have been queued.
200 Event ignored (test flag or unsupported action/status).
401 Missing or invalid X-IPF-Signature, or no secret configured.
400 Invalid JSON, configured username does not exist, or missing snapshot ID.
409 The Sync is currently running; the webhook was received too early.
404 The Sync PK in the URL does not exist.

Multiple Syncs from One IP Fabric Instance

Each Sync has its own webhook entry in PLUGINS_CONFIG, its own URL (with the Sync PK embedded), and its own HMAC secret configured separately in IP Fabric. Create one IP Fabric webhook per Sync.

"webhook_secrets": {
    # Sync for production snapshot
    5:  {"secret": "prod-secret-abc", "username": "ipfabric-bot"},
    # Sync for pre-production snapshot
    6:  {"secret": "preprod-secret-xyz", "username": "ipfabric-bot"},
}

Troubleshooting

Webhook returns 401

  • Confirm the secret in configuration.py exactly matches the one obtained from IP Fabric (no trailing whitespace).
  • Confirm the <sync-pk> in the URL matches the integer PK stored in webhook_secrets.
  • Reload NetBox after changing configuration.py.

Webhook returns 400 — username not found

  • Ensure the username value in webhook_secrets matches an existing NetBox user (case-sensitive).
  • The user must have the ipfabric_netbox.sync_ipfabricsync permission.

Ingestion job fails with “snapshot not found”

  • The source sync that runs before the ingestion sync did not discover the snapshot. Check the source sync job logs for errors (e.g. IP Fabric API connectivity, invalid API token).
  • If multiple RQ workers are running, the ingestion job may have started before the source sync finished. Consider reducing worker concurrency or re-running manually.

Webhook returns 409

  • The Sync was already running when the webhook arrived. IP Fabric will not retry automatically; re-trigger manually from the Sync detail page once the current run finishes.