This guide is for Rainforest platforms running their software inside a private network, with no public inbound HTTPS endpoint available to receive webhooks. It covers three patterns for receiving Rainforest webhooks to an on-prem service.

Details about Rainforest event notifications through webhooks are available at the Webhooks overview, including the retry schedule, signing model, and event structure.

Topology for on-prem platforms

On-prem instances differ from cloud deployed instances by the ability to expose an inbound HTTPS endpoint to receive webhooks.

Receiving webhooks on local infrastructure

Receiving real-time event webhooks from Rainforest (such as payin.processing or deposit.processing) requires a secure bridge to bypass local firewalls or NAT without compromising network security.

Secure tunnel

This pattern uses a dedicated agent on your local server to create an encrypted outbound tunnel to a gateway. This allows Rainforest to reach your local endpoint without you having to open any inbound ports on your firewall. Typical commercial implementations of this pattern are done with Cloudflare Tunnel or ngrok.

Note: Ensure your local application still performs a Webhook Signature Validation to ensure the request is originating from Rainforest.

Reverse proxy

If your merchants manage their own DMZ (Demilitarized Zone), you can use a reverse proxy to filter traffic before it hits your internal network.

Setup

1. Place a Load Balancer or Reverse Proxy (Nginx/HAProxy) in your DMZ.
2. Configure the firewall to allow traffic only from Rainforest specific IP ranges, if possible, and/or strictly validate a custom header (configured in the Rainforest portal) at the proxy level.
3. Forward the traffic from the proxy to the internal application server.

Rainforest polling - pull mode

In high-compliance or air-gapped environments where inbound traffic is strictly forbidden, a "Pull" pattern is safer. Instead of Rainforest pushing webhook events, the platform pulls from Rainforest.

In the Rainforest Polling pattern, the on-prem service calls the polling events endpoint on a schedule and pulls events directly from Rainforest. This requires only an outbound HTTPS to Rainforest, but you must integrate the polling logic into your platform's software.

Polling avoids the need to expose an HTTPS endpoint but the tradeoff is delay, since events are only seen on the next poll rather than the moment they occur.

Security considerations

These considerations apply regardless of the pattern selected:

• Validate the Rainforest webhook signature at the final on-prem destination, not only at the cloud or relay edge. A compromised relay otherwise becomes an event injection point.
• Treat the signing key as a secret on par with API keys. Rotate per your standard schedule, store in a secrets manager, and never commit it to source control.
• Pin the four Rainforest source IPs at the first public hop you control. This drops most spurious traffic before any cryptographic work.
• Use mTLS between the public relay and on-prem if you control both ends. This closes off the path even if the public component is breached.
• Apply idempotency at the component consuming the event (relay or platform). Webhooks are at-least-once, and manual replays from the portal can also redeliver events you have already processed. Use the resource ID and event_type as the idempotency key.
• Log every received event with its event_type, resource ID, and signature validation result before any processing branch. This is your audit trail when reconciling with the Rainforest portal.