Skip to content
Guides & References

React to rConfig events with webhooks

How rConfig's Generic JSON webhooks work: the event envelope, checking the signature, retries and auto-disable, and how to design a receiver.

API & DeveloperUpdated
On this page

React to rConfig events with webhooks

A webhook turns rConfig events into HTTP calls to your system: a config changed, a device can’t be reached, a device started failing a policy. Your code doesn’t have to poll; rConfig tells it. This page covers the Generic JSON format, which is the one to use when your own code receives the event. Setting a webhook up, and the full event list, are in the webhook notifications docs.

rConfig docsWebhook NotificationsSend rConfig V8 events to Slack, Microsoft Teams, Discord, Google Chat or any HTTP endpoint, with per-webhook event and severity filters.Read the webhook notifications docs

What arrives

Each event is an HTTP POST with a JSON body in a fixed envelope:

Generic JSON envelope
{
"schema_version": 1,
"id": "6f1c2b9e-4d0a-4c4e-9a51-2f3d8e7b1c20",
"event": "config.changed",
"category": "config",
"severity": "warning",
"occurred_at": "2026-11-15T09:42:17+00:00",
"title": "Configuration changed on edge-rtr-01",
"summary": "A configuration change was detected on edge-rtr-01 for command 'show running-config'.",
"url": "https://rconfig.example.com/configs/view/5521?ref=device-view",
"instance": { "name": "rConfig", "url": "https://rconfig.example.com", "version": "8.4.3" },
"data": { }
}

The envelope is the same for every event. What goes in data depends on the event. For config.changed it is:

data for config.changed
{
"device": { "id": 12, "name": "edge-rtr-01", "category": "Routers" },
"config": { "id": 5521, "command": "show running-config", "version": 42 },
"diff": {
"lines": [
{ "type": " ", "line": "41", "text": "ntp server 192.0.2.123" },
{ "type": "-", "line": "42", "text": "logging host 192.0.2.50" },
{ "type": "+", "line": "42", "text": "logging host 198.51.100.50" }
],
"total_lines": 3,
"truncated": false
},
"diff_error": null
}
  • diff.lines holds at most 200 lines; truncated is true when there were more. Fetch the full config or diff through the API when you need it all.
  • type is + for an added line, - for a removed one, a space for context, and skipped for a gap between changed sections.
  • When rConfig couldn’t build the diff, diff is null and diff_error says why.

schema_version is there so the envelope can change in future without breaking receivers. Check it, and reject versions your code doesn’t know.


Headers

Header What it carries
X-rConfig-Event The event name, such as config.changed
X-rConfig-Event-Id The event’s id from the body
X-rConfig-Delivery A unique ID for this delivery attempt, shown in the webhook’s delivery log in rConfig
X-rConfig-Signature The signature, below

Any custom headers you add to the webhook (an API key your receiver expects, for example) are sent too. They can’t override the X-rConfig- headers.


Checking the signature

Anyone who learns your receiver’s URL can post to it. The signature proves a request came from your rConfig and wasn’t altered.

The header looks like X-rConfig-Signature: t=1763199737,v1=5d0c…. To check it:

  1. Split the header on , and read t (a Unix timestamp) and v1 (a hex digest).
  2. Reject the request if t is more than 300 seconds from your clock. That stops an old request being replayed.
  3. Compute HMAC-SHA256 over the string <t>.<raw body> with the webhook’s signing secret, as lowercase hex.
  4. Compare it with v1 using a constant-time comparison. Reject on any mismatch.

Use the raw request body, byte for byte. Parsing the JSON and re-serialising it changes the bytes and the signature won’t match.

verify_signature.py
import hashlib
import hmac
import time
def verify(secret: str, header: str, raw_body: bytes, tolerance: int = 300) -> bool:
"""Check an X-rConfig-Signature header against the raw request body."""
parts = dict(p.strip().split("=", 1) for p in header.split(",") if "=" in p)
timestamp, digest = parts.get("t", ""), parts.get("v1", "")
if not timestamp.isdigit() or not digest:
return False
if abs(time.time() - int(timestamp)) > tolerance:
return False
expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, digest)

The signing secret starts whsec_. rConfig shows it once, when you create the webhook or rotate the secret. Signatures are only sent with the Generic JSON format.


Retries and auto-disable

What happens Detail
Success Any 2xx response within the webhook’s timeout (1 to 30 seconds, default 10)
Retries Up to 4 attempts in all, waiting 30 seconds, 2 minutes and 10 minutes between them
Auto-disable After 10 failed deliveries in a row, rConfig switches the webhook off, logs it, and raises a system.notification_error notification

Every attempt, successful or not, is recorded in the webhook’s delivery log in rConfig. Once you’ve fixed a receiver that was switched off, turn the webhook back on in Settings → Notifications.


Designing a receiver

  • Answer fast. Check the signature, store or queue the event, and return 200 straight away. Do the slow work (calling the API, opening a ticket) afterwards. A receiver that takes longer than the timeout counts as a failure and gets the event again.
  • Expect duplicates. A retry after a timeout can deliver an event your receiver already handled. Use the event id to ignore repeats.
  • Don’t trust the body for decisions that matter. The event says what happened; if your code is about to act on it, fetch the current state through the REST API first.
  • Subscribe narrowly. Pick only the events the receiver handles. Fewer events means fewer chances to fail and be switched off.
  • Use the test button. Send test posts a webhook.test event before you save. Have the receiver accept it and return 200 without acting on it.

Type to search.