On-Premises Webhook Destinations
This guide explains how to let an on-premises OpenProdkt deployment send webhooks to receivers on private networks. It is for operators of self-hosted deployments.
Default behavior
Webhook destinations are denied by default. In a default deployment:
- The API rejects a webhook endpoint whose host resolves to a private, loopback, link-local, multicast, or unspecified address.
- The delivery worker checks the resolved address again before it connects.
- Delivery does not follow HTTP redirects.
localhostandmetadata.google.internalare refused by name.- Cloud metadata addresses are blocked.
Tenants cannot change these rules. Only the deployment environment can open a private range, and only for the whole deployment.
Open a private range
Set OPK_WEBHOOK_ALLOWED_CIDRS to a comma-separated list of IPv4 or IPv6 CIDR ranges. Set it on both the API and the worker, then restart both.
OPK_WEBHOOK_ALLOWED_CIDRS=10.20.30.0/24,fd00:1234::/64
- Keep each range as narrow as the receivers need.
- Do not use shared address space (
100.64.0.0/10) unless every host in it is a receiver you control. - An empty value keeps the default deny policy.
Values that stop startup
The API and the worker exit at startup, and log the variable name, when the value contains any of the following:
- An invalid CIDR.
- A default route (
0.0.0.0/0or::/0). - An IPv4-mapped prefix (
::ffff:0:0/96). - A range that contains a cloud metadata address, such as
169.254.169.254,169.254.170.2,100.100.100.200,192.0.0.192, orfd00:ec2::254. For example,169.254.0.0/16,192.0.0.0/8, and100.64.0.0/10are all refused.
Use HTTPS where possible
When OPK_PRODUCT_MODE is saas, which is the default, webhook URLs must use https. Other product modes accept plain http, so on-premises receivers without TLS can be used. Use https whenever the receiver supports it.
Apply and verify
- Set
OPK_WEBHOOK_ALLOWED_CIDRSon the API and the worker, then restart both. - Confirm that both processes stay running. A refused value stops them at startup.
- Create a webhook endpoint whose host is inside the range. The API should accept it.
- Create an endpoint whose host is outside every range. The API should refuse it with a validation error.
- Trigger an event that sends a webhook, such as an approval request, and confirm that the receiver gets it.
Roll back
Unset OPK_WEBHOOK_ALLOWED_CIDRS (or remove the range) and restart the API and the worker. The worker checks the policy again at connect time, so deliveries to receivers in a removed range stop. Existing endpoints remain in the deployment. Update or remove any endpoint that should no longer receive events.
Related
- Security Model: webhook destination rules.
- Developer Guide: webhook behavior for integrations.
- Transparent Proxy: on-premises network setup.