Worldline sends webhook notifications to your endpoint when payment events occur. You need to verify that these requests are authentic and come from Worldline, not from an unauthorized source. If you want to add additional security to validate the webhooks are sent by us, you can secure your webhooks by choosing an approach that best fits your deployment environment and network requirements. You can implement one approach or combine both for added validation.

• Application-level security: Custom headers - You can add a secret HTTP header to each webhook request for authentication. Your endpoint validates the header against your configured value. This approach works well when you deploy in cloud environments where IP addresses change frequently and firewall reconfiguration is impractical.

• Network-level security: DNS-based whitelisting - Configure your firewall to allow requests from Worldline's DNS domain. Instead of maintaining a static IP whitelist, the domain automatically resolves to current IP addresses. This means your firewall rules remain valid even when our infrastructure changes. Use this approach when you deploy on-premises and manage your own firewall.

You can implement both methods simultaneously. Combining application-level and network-level security provides multiple validation layers for webhook requests.

Key benefits

Custom headers

• Simple setup in the Configuration Center
• Live within 10 minutes (no code changes needed
• Ideal for cloud-native deployments
• Application-level security

DNS-based whitelisting

• Automatic IP updates (no manual maintenance)
• Network-level control
• Perfect for on-premises firewalls
• Set-and-forget deployment

Which approach should you choose?

You can choose a security approach based on your deployment environment and security requirements. The comparison table below shows which approach is suitable for cloud, on-premises, and hybrid deployments.

Integration of custom headers

Overview

Custom headers provide application-level authentication. Worldline includes a custom HTTP header in every webhook call. Your endpoint validates the header to confirm legitimacy.

Requirements:

• Header name must include the X- prefix.
• Maximum header length is 256 characters.
• Allowed characters: a-z, A-Z, 0-9, underscore (_), colon (:), semicolon (;), period (.), comma (,), slash (/), backslash (), quotes ("), question mark (?), exclamation mark (!), brackets ([ ]), parentheses ( ), @ symbol, angle brackets (< >), hyphen (-), plus (+), asterisk (*), hash (#), dollar sign ($), ampersand (&), backtick (`), pipe (|), tilde (~), caret (^), percent (%).
• You need to configure the header in Integration Dashboards.

To set up custom headers, access Integration Dashboards in the Configuration Center and go to Webhooks header.

1. Go to webhooks header in the webhooks tab.

1. Click on add webhooks header.

1. Define header name and value.

1. Check the header status and make more changes if needed.

Key implementation details

• Headers are active immediately after configuration—no additional activation step is required.
• Allow up to 10 minutes for headers to propagate across the system.
• View configured headers in the Webhook Log Details section of Integration Dashboards.
• Headers apply to all merchant IDs in your account.
• Caching applies to headers similar to webhook endpoints.
• Headers cannot override X-GCS-* prefixed headers.

FAQ

• When do headers become active after creation?
  Headers become active immediately upon creation. No manual activation step is required. Allow up to 10 minutes for full propagation across all systems.
• What are the header naming requirements and restrictions?
  Headers must use the X- prefix (mandatory). Prefixes like X-GCS-* are blacklisted to avoid collisions with system headers. Maximum length is 256 characters. Allowed characters include letters, numbers, underscore, colon, semicolon, period, comma, and common punctuation marks.
• What is the advantage of custom headers compared to the existing webhooks key ID?
  Custom headers provide simple, application-level authentication without complexity. They replace IP whitelist functionality that was lost during cloud migration, offering merchants an easier authentication option for cloud-native environments.
• Can I customize the webhook user agent?
  Yes. The user agent can be customized to something like X-custom-header for easier identification in your logs and monitoring systems.
• Can I add different headers to different webhook endpoints?
  No. Headers apply to all webhook requests from your account. Event types are distinguished from the webhook payload itself, so different headers per endpoint are unnecessary.
• Why should I avoid executable content like .exe in header values?
  Validation checks prevent executable content to protect against injection attacks and ensure the security of your webhook stream.

Integration of DNS-based whitelisting

Overview

DNS-based whitelisting allows you to whitelist Worldline's DNS domain instead of maintaining a static IP list. Your firewall automatically resolves the domain to current IP addresses, so webhooks continue flowing without requiring manual updates when IPs change.

DNS domain: webhooks-incoming-ipadresses.connect.worldline-solutions.com

How it works

1. We provide you with the DNS domain.
2. You configure firewall/web server to allow inbound from our domain.
3. Firewall continuously resolves domain to current IPs.
4. Webhook traffic is accepted automatically.
5. (Optional) You set up automation to refresh IP list every 10 minutes.

Benefits of DNS-based whitelisting

• No manual IP maintenance: DNS automatically resolves to current IP addresses without requiring configuration changes.
• Supports dynamic infrastructure: IP addresses update without interrupting webhook delivery.
• Continuous webhook delivery: Webhooks are not interrupted when IP addresses change.
• Network-level validation: Only traffic from the whitelisted Worldline domain is accepted.

What you need to know

• DNS-based whitelisting requires firewall/network-level configuration (admin access).
• Different web servers require different configuration approaches.
• You have to configure it on your end.
• DNS resolution must be working properly for whitelisting to function.

Select your web server for implementation guide

Apache server implementation

Apache has native support for DNS-based whitelisting via the mod_authz_host module.

1. Enable the mod_authz_host module LoadModule authz_host_module modules/mod_authz_host.so
2. Configure the whitelist in your Apache configuration.Require forward-dns webhooks-incoming-ipadresses.connect.worldline-solutions.com
3. Restart Apache sudo service apache2 restart

Result: Requests from the DNS domain are now whitelisted automatically.