| WFORCE_WEBHOOK(5) | WFORCE_WEBHOOK(5) |
NAME¶
wforce_webhook - Documentation for wforce webhook functionality
DESCRIPTION¶
The wforce daemon supports generating webhooks which run for specific events. The list of supported events, example payload for those events, and the supported configuration keys for those events are documented here. A summary of the custom HTTP(S) POST headers is also included.
WEBHOOK EVENTS¶
See wforce.conf(5) for details of the "addWebHook()" configuration setting. The following events are available for generating webhooks:
•report - Runs each time a valid report command is
received. The webhook includes the report request payload but not the report
response. An example payload for the HTTP post is shown below:
{"remote": "1.4.3.1", "success": false, "policy_reject":
false, "attrs": {"cos": "basic"},
"login": "webhooktest@foobar.com", "pwhash": "1234",
"t": 1472718468.412865}
•allow - Runs each time a valid allow command is
received. The webhook includes the request payload and the response payload.
This hook can be filtered on the return value using the
"allow_filter" configuration key. An example payload for the HTTP
post is shown below:
{"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 each time a valid reset command is
received. The webhook includes the request payload. An example payload for the
HTTP post is shown below:
{"ip": "1.4.3.3", "login": "webhooktest@foobar.com"}
•addbl - Runs each time a blacklist entry is added
(from Lua or the REST API). The webhook includes the request payload. An
example payload for the HTTP post is shown below:
{"key": "webhooktest@foobar.com",
"reason": "Too many different bad password attempts",
"expire_secs": 10, "bl_type": "login_bl"}
•delbl - Runs each time a blacklist entry is
deleted (from Lua or the REST API). The webhook includes the request payload.
An example payload for the HTTP post is shown below:
{"key": "1.4.3.3:webhooktest@foobar.com",
"bl_type": "ip_login_bl"}
•addwl - Runs each time a whitelist entry is added
(from Lua or the REST API). The webhook includes the request payload. An
example payload for the HTTP post is shown below:
{"key": "webhooktest@foobar.com",
"reason": "This user is an admin",
"expire_secs": 10, "wl_type": "login_wl"}
•delwl - Runs each time a whitelist entry is
deleted (from Lua or the REST API). The webhook includes the request payload.
An example payload for the HTTP post is shown below:
{"key": "1.4.3.3:webhooktest@foobar.com",
"wl_type": "ip_login_wl"}
•expirebl - Runs each time a blacklist entry is
expired. An example payload for the HTTP post is shown below:
{"key": "webhooktest@foobar.com", "bl_type": "login_bl"}
•expirewl - Runs each time a whitelist entry is
expired. An example payload for the HTTP post is shown below:
{"key": "webhooktest@foobar.com", "wl_type": "login_wl"}
CUSTOM WEBHOOKS¶
See wforce.conf(5) for details of the "addCustomWebHook()" configuration setting. This enables custom webhooks to be generated from Lua.
WEBHOOK CONFIGURATION KEYS¶
See wforce.conf(5) for details of the "addWebHook()" configuration setting. The following configuration keys can be used for all events:
•url - The URL that the webhook should POST to.
You can add date macros into the URL that will be substituted when the hook is
run. The following macros 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 that is used to generate the
Hmac digest for the X-Wforce-Signature header. 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 - This configuration key is now
deprecated - setting it will have no effect. Use
"setNumWebHookConnsPerThread()" configuration setting instead (see
wforce.conf(5)).
•basic-auth - Adds an Authorization header to
Webhooks, for servers which 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"
•kafka - When this is set to "true" then
the webhook will be sent with a Content-Type of
"application/vnd.kafka.json.v2+json" and the json will be wrapped
according to the Kafka REST Proxy requirements (
<https://docs.confluent.io/current/kafka-rest/api.html>). The webhook
"url" config key should be set to the correct topic, e.g.
"http://kafka-rest:8082/topics/foo" for the topic named
"foo".
The following configuration keys are custom to specific events:
•allow_filter - Filters allow webhooks based on
the allow response status. If not specified, the webhook runs for all allow
events. Possible values are: "reject", "allow" and
"tarpit". The values are OR’d together, so specifying all
values will have the same effect as not specifying allow_filter. 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 will set the HTTP Content-Type header to the
value specified in this key, so ensure it is a valid MIME Content-Type. For
example:
config_key["content-type"] = "text/plain"
WEBHOOK CUSTOM HTTP HEADERS¶
The following custom headers will be added to the POST request for each event:
•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 will contain 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 cannot be changed for normal webhooks. Custom webhooks however can change it using the "content-type" configuration key.
FILES¶
/etc/wforce.conf
SEE ALSO¶
wforce(1) wforce_webhook(5) wforce_api(7)
AUTHOR¶
Open-Xchange 2018
| 2025-10-23 |