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:
{ "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:
{ "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.linesholds at most 200 lines;truncatedistruewhen there were more. Fetch the full config or diff through the API when you need it all.typeis+for an added line,-for a removed one, a space for context, andskippedfor a gap between changed sections.- When rConfig couldn’t build the diff,
diffisnullanddiff_errorsays 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:
- Split the header on
,and readt(a Unix timestamp) andv1(a hex digest). - Reject the request if
tis more than 300 seconds from your clock. That stops an old request being replayed. - Compute HMAC-SHA256 over the string
<t>.<raw body>with the webhook’s signing secret, as lowercase hex. - Compare it with
v1using 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.
import hashlibimport hmacimport 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
200straight 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
idto 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.testevent before you save. Have the receiver accept it and return200without acting on it.