Webhook Security Features

Webhook Security Features

Protecting your incoming webhooks is crucial to ensure only authorized systems can send data to your Tadabase app. The webhook catcher provides multiple layers of security to validate incoming requests.

Why Webhook Security Matters

Without proper security, anyone who discovers your webhook URL could potentially send malicious or incorrect data to your app. Security features help you:

• Verify requests are coming from legitimate sources
• Prevent unauthorized data injection
• Protect against spam or malicious attacks
• Ensure data integrity and authenticity

Available Security Options

The webhook catcher offers four main security methods that can be used individually or combined:

1. IP Address Filtering
2. Host Allowlisting
3. User Agent Validation
4. Signature Verification
5. Basic Authentication

IP Address Filtering

Control which IP addresses can send requests to your webhook.

How It Works

You can configure your webhook to either:

• Allow only specific IPs (allowlist mode)
• Block specific IPs (blocklist mode)

Setting Up IP Filtering

1. Edit your webhook
2. Navigate to the "Security" section
3. Select "IP Address Filtering"
4. Choose your rule type:
   • Allow Only These IPs: Only listed IPs can send requests
   • Block These IPs: Listed IPs are blocked; all others are allowed
5. Enter IP addresses (one per line)
6. Save your changes

IP Address Formats

You can enter IP addresses in the following formats:

192.168.1.1
203.0.113.0/24
2001:db8::1

Be careful when using allowlist mode. If you misconfigure IPs, legitimate requests will be rejected. Always test thoroughly.

Finding Service IP Addresses

Most webhook providers publish their IP addresses. Check your service's documentation:

• Stripe: https://stripe.com/docs/ips
• Shopify: Check Shopify's webhook documentation
• SendGrid: See SendGrid's IP address list

Host Allowlisting

Restrict webhooks to only accept requests from specific hostnames or domains.

How It Works

The webhook checks the request's origin host and compares it to your allowlist. Only requests from approved hosts are processed.

Setting Up Host Allowlisting

1. Edit your webhook
2. Navigate to the "Security" section
3. Select "Host Allowlist"
4. Enter allowed hostnames (one per line)
5. Save your changes

Hostname Formats

api.stripe.com
*.github.com
webhook.example.com

You can use wildcards (*) to match subdomains.

User Agent Validation

Verify requests are coming from expected applications by checking the User-Agent header.

How It Works

Each HTTP request includes a User-Agent string that identifies the application making the request. You can configure your webhook to only accept requests with specific User-Agent values.

Setting Up User Agent Validation

1. Edit your webhook
2. Navigate to the "Security" section
3. Select "User Agent Validation"
4. Enter allowed user agent strings (one per line)
5. Save your changes

Example User Agents

Stripe/1.0
Shopify-Webhook
GitHub-Hookshot

Check your service's documentation to find their User-Agent string. You can also view the User-Agent in your webhook logs from test requests.

Signature Verification

The most secure method - verify requests using cryptographic signatures.

How It Works

Many webhook providers include a signature in the request headers. This signature is created using a secret key and the request payload. Your webhook can verify this signature to ensure:

• The request came from the legitimate service
• The payload hasn't been tampered with

Setting Up Signature Verification

1. Edit your webhook
2. Navigate to the "Security" section
3. Select "Signature Verification"
4. Enter the signature header name (e.g., "X-Stripe-Signature")
5. Enter your webhook secret/signing key from the service
6. Save your changes

Common Signature Headers

• Stripe: X-Stripe-Signature
• GitHub: X-Hub-Signature-256
• Shopify: X-Shopify-Hmac-SHA256
• Twilio: X-Twilio-Signature

Getting Your Webhook Secret

Each service provides a webhook secret or signing key when you create a webhook endpoint. This is typically found in:

• The webhook settings page of the service
• Revealed when you first create the webhook
• Available in developer/API settings

Keep your webhook secret confidential. Anyone with access to it can forge valid requests.

Basic Authentication

Require a username and password for webhook requests.

How It Works

The webhook will only accept requests that include valid Basic Authentication credentials in the request headers.

Setting Up Basic Authentication

1. Edit your webhook
2. Navigate to the "Security" section
3. Enable "Basic Authentication"
4. Set a username
5. Set a strong password
6. Save your changes

Configuring Services to Use Basic Auth

When entering your webhook URL in external services, include credentials:

https://username:password@catch.tadabase.io/webhook/abc123

Or configure authentication separately if the service supports it.

Combining Security Methods

For maximum security, you can enable multiple security features simultaneously. All enabled security checks must pass for a request to be processed.

Recommended Combinations

• High Security: IP Filtering + Signature Verification
• Medium Security: Host Allowlist + User Agent Validation
• Basic Security: User Agent Validation or IP Filtering

More security layers provide better protection but require more configuration. Balance security needs with setup complexity.

Testing Security Configuration

After configuring security features:

1. Send a test webhook from your service
2. Check the webhook logs to verify it was accepted
3. Try sending a request that should be blocked (different IP, missing signature, etc.)
4. Confirm blocked requests are rejected with appropriate error messages

Using Sample Requests

The "Test Request" feature bypasses security checks, allowing you to test field mapping without configuring security first. Once field mapping is working, add security features.

Security Error Messages

When a request fails security validation, the webhook returns specific error messages:

• IP Blocked: "Request from unauthorized IP address"
• Invalid Signature: "Webhook signature verification failed"
• Unauthorized Host: "Request from unauthorized host"
• Invalid User Agent: "User agent not authorized"
• Authentication Failed: "Basic authentication required" or "Invalid credentials"

These error messages appear in your webhook logs and are returned to the requesting service.

Monitoring Security

Review Failed Requests

Regularly check your webhook logs for failed authentication attempts:

1. Go to your webhook detail page
2. View the call logs
3. Filter for failed requests
4. Review error messages to identify security issues

Enable Failure Notifications

Set up email notifications for failed webhook calls to be immediately alerted of potential security issues or misconfigurations.

Best Practices

• Always use signature verification when available - it's the most secure option
• Keep secrets secure - never share webhook secrets or commit them to version control
• Rotate secrets periodically - update webhook secrets every few months
• Use allowlists, not blocklists - explicitly allowing sources is more secure than trying to block bad actors
• Test thoroughly - verify security settings work as expected before going live
• Monitor logs - regularly review webhook logs for suspicious activity
• Start permissive, then restrict - get webhooks working first, then add security layer by layer
• Document your configuration - keep notes about which security features are enabled and why

Troubleshooting Security Issues

Legitimate Requests Being Blocked

• Verify IP addresses are correctly entered
• Check if the service's IP addresses have changed
• Ensure hostname matches exactly (check for www vs non-www)
• Verify the signature secret is correct
• Confirm the signature header name matches the service's format

Unable to Test Security

• Use the webhook logs to see the actual values being sent (IP, User-Agent, headers)
• Compare log values to your security configuration
• Temporarily disable security to confirm other aspects are working
• Re-enable security features one at a time to identify the issue

Service Documentation Unclear

• Check the service's community forums or support channels
• Look for webhook examples in the service's documentation
• Contact the service's support team for webhook configuration help
• Search for third-party guides or tutorials