← Back to documentation

IP Allowlists

Add allowed source addresses and reject requests from other addresses.

4 min read

An IP allowlist is a list of source IP addresses that can send requests to a webhook endpoint. PayloadRelay accepts a request only from an address that matches. A different address receives 403 Forbidden.

How IP allowlists operate#

If an endpoint has an IP allowlist, PayloadRelay examines each inbound request before the authentication, the validation, and the delivery. If the source IP matches no entry, PayloadRelay rejects the request:

  • HTTP response: 403 Forbidden
  • Activity outcome: IP Blocked (IP_BLOCKED)
  • The request does not consume monthly quota.

PayloadRelay applies the IP filter to an enabled endpoint only. A disabled endpoint returns 404 for every request, and the source IP has no effect. PayloadRelay gets the source IP from trusted connection data. It ignores an untrusted forwarding header. A client cannot get past an allowlist with a request header.

Before you start#

  • Make sure that you can edit the endpoint.
  • Use a webhook endpoint. An IP allowlist is not available on an email ingestion endpoint.

Procedure#

1. Open the endpoint security configuration#

  1. Open the endpoint in the Endpoints page.
  2. Open the Security tab.
  3. Scroll to the IP allowlist section.

2. Add allowed IP addresses#

Select Add IP and enter an IP address or a CIDR block:

FormatExampleMatches
Single IPv4203.0.113.5That one address only
IPv4 CIDR198.51.100.0/24Every address from 198.51.100.0 to 198.51.100.255
Single IPv62001:db8::1That one address only
IPv6 CIDR2001:db8::/32Every address in the prefix 2001:db8

3. Configure IP version (optional)#

If your senders use IPv4 only or IPv6 only, you can limit the allowed IP version:

Version filterEffect
Any (default)Accept IPv4 and IPv6 from the allowed addresses
IPv4 onlyReject every IPv6 request, also from an allowed address
IPv6 onlyReject every IPv4 request, also from an allowed address

4. Save and send a test request#

  1. Save the endpoint.
  2. Send a request from an allowed IP. Make sure that Activity shows Completed (ACCEPTED).
  3. Send a request from an IP that is not in the list. Make sure that Activity shows IP Blocked (IP_BLOCKED).

Allowlist behavior#

ScenarioResult
The allowlist is empty (default)PayloadRelay accepts every IP
The request IP matches an entryThe request continues to the authentication and the validation
The request IP matches no entry403 Forbidden, recorded as IP_BLOCKED
The endpoint is disabled404 for every IP. PayloadRelay does not apply the IP filter.

Common use cases#

  • Server-to-server integrations: allow the static IP of the application server only.
  • CI/CD pipelines: allow the IP addresses of the GitHub Actions runners or the Jenkins runners only.
  • Compliance rules: allow the known corporate network ranges only.

Monitoring blocked requests#

In Request activity, select Errors and find the IP Blocked (IP_BLOCKED) rows. Expand a row that is not aggregated to see its Originating IP. For a known address, use the exact Source IP filter. An aggregated row does not show one source IP.

Common issues and fixes#

  • PayloadRelay blocks my requests: make sure that the allowlist contains the public IP, and not the internal LAN IP. To find the external IP, use curl ifconfig.me.
  • The CIDR does not match: make sure that the CIDR notation is correct. 192.168.1.0/24 covers .0 to .255. /32 is one address.
  • PayloadRelay blocks the IPv6 senders: add the IPv6 address or the IPv6 CIDR to the allowlist. You can also set the IP version filter to Any in place of IPv4 only.
← Back to documentation