Skip to main content

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.
  • localhost and metadata.google.internal are 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/0 or ::/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, or fd00:ec2::254. For example, 169.254.0.0/16, 192.0.0.0/8, and 100.64.0.0/10 are 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​

  1. Set OPK_WEBHOOK_ALLOWED_CIDRS on the API and the worker, then restart both.
  2. Confirm that both processes stay running. A refused value stops them at startup.
  3. Create a webhook endpoint whose host is inside the range. The API should accept it.
  4. Create an endpoint whose host is outside every range. The API should refuse it with a validation error.
  5. 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.