WFORCE_WEBHOOK(5)

📦
version 3.0.0 · 3 versions
, in ubuntu stonking

💖 wforce_webhook 💖

okay bestie, listen up — this is the wforce_webhook(5) manual page, and it's the whole entire guide to the webhook functionality in the wforce daemon. section 5, diva behavior, no notes.

so here's the vibe: the wforce daemon can generate webhooks that fire off for specific events. this page documents which events exist, what the example payload looks like for each one, and which configuration keys go with them. plus a lil summary of the custom HTTP(S) POST headers at the end. it's giving complete. it's giving documented. 🎀

✨ WEBHOOK EVENTS ✨

peep wforce.conf(5) for the details on the "addWebHook()" configuration setting, okay? that's where the lore lives. and these are the events you can generate webhooks for, bestie:

  • report — runs every single time a valid report command comes through 🫶. the webhook includes the report request payload but not the report response. here's the example payload for the HTTP post:
{"remote": "1.4.3.1", "success": false, "policy_reject":
false, "attrs": {"cos": "basic"},
"login": "webhooktest@foobar.com", "pwhash": "1234",
"t": 1472718468.412865}
  • allow — runs every time a valid allow command comes through 💅. this one's extra, it includes both the request payload and the response payload. you can filter this hook on the return value using the "allow_filter" configuration key (more on that below). example payload for the HTTP post:
{"request": {"remote": "1.4.3.2", "success": false,
"policy_reject": true, "attrs": {},
"login": "webhooktest@foobar.com", "pwhash": "1234",
"t": 1472718469.827362}, "response": {"msg": "", "status": 0}}
  • reset — runs every time a valid reset command comes through 🌸. includes the request payload. example payload for the HTTP post:
{"ip": "1.4.3.3", "login": "webhooktest@foobar.com"}
  • addbl — runs every time a blacklist entry gets added (whether that's from Lua or the REST API 👀). includes the request payload. example payload for the HTTP post:
{"key": "webhooktest@foobar.com",
"reason": "Too many different bad password attempts",
"expire_secs": 10, "bl_type": "login_bl"}
  • delbl — runs every time a blacklist entry gets deleted (from Lua or the REST API). includes the request payload. example payload for the HTTP post:
{"key": "1.4.3.3:webhooktest@foobar.com",
"bl_type": "ip_login_bl"}
  • addwl — runs every time a whitelist entry gets added (from Lua or the REST API). includes the request payload. example payload for the HTTP post:
{"key": "webhooktest@foobar.com",
"reason": "This user is an admin",
"expire_secs": 10, "wl_type": "login_wl"}
  • delwl — runs every time a whitelist entry gets deleted (from Lua or the REST API). includes the request payload. example payload for the HTTP post:
{"key": "1.4.3.3:webhooktest@foobar.com",
"wl_type": "ip_login_wl"}
  • expirebl — runs every time a blacklist entry expires ⏳. example payload for the HTTP post:
{"key": "webhooktest@foobar.com", "bl_type": "login_bl"}
  • expirewl — runs every time a whitelist entry expires ⏳. example payload for the HTTP post:
{"key": "webhooktest@foobar.com", "wl_type": "login_wl"}

🦋 CUSTOM WEBHOOKS 🦋

again, go read wforce.conf(5) for the deets on the "addCustomWebHook()" configuration setting 💜. this is the one that lets you generate custom webhooks straight from Lua. main character energy fr.

👑 WEBHOOK CONFIGURATION KEYS 👑

yeah yeah, wforce.conf(5) again for the "addWebHook()" setting. now these keys right here work for all events, no cap:

  • url — the URL that the webhook should POST to 💫. you can drop date macros into the URL and they'll get substituted when the hook runs. the macros that are supported: %{YYYY}, %{MM}, %{dd}. supports http and https. for example:
config_key["url"] = "https://example.com/foo"
config_key["url"] = "https://example.com/foo/logstash-%{YYYY}-${MM}-%{dd}"
  • secret — a string used to generate the Hmac digest for the X-Wforce-Signature header 🔐. it should be unique for each webhook so that the remote web server can verify the digest as being authentic. for example:
config_key["secret"] = "12345"
  • num_conns — bestie. this configuration key is now deprecated 💀 — setting it will have no effect. use the "setNumWebHookConnsPerThread()" configuration setting instead (see wforce.conf(5)).
  • basic-auth — adds an Authorization header to Webhooks, for servers that expect Basic Authentication 🌈. the username and password are provided as "user:pass". for example:
config_key["basic-auth"] = "wforce:super"
  • api-key — adds an X-API-Key header to Webhooks, for servers that expect such a header for Authorization 🔑. for example:
config_key["api-key"] = "myapikeysecret"

and these ones? these are custom to specific events, babes:

  • allow_filter — filters allow webhooks based on the allow response status 🌟. if you don't specify it, the webhook runs for all allow events. possible values are: "reject", "allow" and "tarpit". the values are OR'd together, so specifying all the values has the same effect as not specifying allow_filter at all. for example:
config_key["allow_filter"] = "allow reject"
config_key["allow_filter"] = "tarpit allow"
config_key["allow_filter"] = "reject"
  • content-type — only custom webhooks can set a custom content-type 🙈. doing so sets the HTTP Content-Type header to whatever value you put in this key, so pls make sure it's a valid MIME Content-Type. for example:
config_key["content-type"] = "text/plain"

💌 WEBHOOK CUSTOM HTTP HEADERS 💌

these custom headers get added to the POST request for every event, periodt:

  • X-Wforce-Event — the name of the event, e.g. "report".
  • X-Wforce-HookID — the ID of the WebHook (use "showWebHooks()" in the console to see the list of IDs.
  • X-Wforce-Signature — if the "secret" configuration key is specified, this header contains a base64-encoded HMAC-SHA256 digest of the POST body 🔐.
  • X-Wforce-Delivery — a unique ID for this webhook ✨.

🎀 WEBHOOK HTTP CONTENT-TYPE HEADER 🎀

the HTTP Content-Type header defaults to application/json, and it cannot be changed for normal webhooks. custom webhooks, though? they can change it using the "content-type" configuration key 💅.

📁 FILES 📁

  • /etc/wforce.conf

👀 SEE ALSO 👀

🫶 AUTHOR 🫶

Open-Xchange 2018

and that's the whole page bestie, you ate it, you're literally an expert now 🧚💖 this lil doc was brought to you by Open-Xchange, 2018 copyright vibes, dated 2026-07-28 — slay, iconic, no further questions 💅✨

📦 where this page comes from