Forwarding (Proxying)

​

Overview

​

Why Use Forwarding?

• Multiple Destinations: Send a single event to up to 3 different URLs simultaneously
• Secure Verification: Each forwarded request includes cryptographic signatures so recipients can verify authenticity
• Easy Integration: Works with Zapier, Make, IFTTT, custom APIs, and any HTTP endpoint
• Complete Transparency: View the history of every forwarded request with response details
• Original Data Preserved: The exact event payload is forwarded without modification
• Works with Everything: Compatible with Private Mode, Time Sensitive notifications, and all other features

​

When to Use Forwarding

​

When NOT to Use Forwarding

• No external services needed — If you only need mobile notifications, standard webhooks are simpler
• Service can’t handle HTTP POST — Your destination must accept HTTP POST requests
• Need data transformation — Hookr forwards data as-is; use an intermediary service for transformations

​

How It Works

​

What Happens When Forwarding Is Enabled

1. ✅ Event arrives — Hookr receives the webhook at your unique URL
2. ✅ Notification sent — You get a push notification (if a message is configured)
3. ✅ Data forwarded — The complete event payload is sent to each configured URL
4. ✅ Request signed — Each forwarded request includes an HMAC SHA256 cryptographic signature
5. ✅ History recorded — Forwarding results (status, response, timing) are saved for review

​

Data Flow Comparison

​

What Gets Forwarded

• All JSON fields from the original request
• Query string parameters
• Original HTTP method (POST, PUT, etc.)
• Exact data structure (no transformation)

​

Setup: Enabling Forwarding

1. Open your webhook — Find the webhook you want to enable forwarding on
2. Edit the webhook — Click the edit button or settings
3. Toggle “Enable Forwarding” — This reveals the forwarding configuration options
4. Add destination URLs — Add 1-3 URLs where events should be forwarded:
   • Click the + button to add a URL field
   • Enter a valid https:// or http:// URL
   • Click - to remove unwanted URLs
5. Copy your secret — A forwarding secret is automatically generated:
   • Displayed as masked text: XXXX...XXXX
   • Click the copy button to copy it
   • Click reset to generate a new secret anytime
6. Save your webhook — Future events will be automatically forwarded

​

URL Requirements

• Format: Must be a valid HTTP or HTTPS URL
• Prefix: Must start with http:// or https://
• Count: Enter 1-3 URLs (fields can be left empty)
• Length: Each URL must be 2,048 characters or less

• https://zapier.com/hooks/catch/123456/abc
• https://api.myapp.com/webhooks/events
• https://example.com/webhook?token=abc123
• http://localhost:3000/webhook (for local testing)

​

Secret Key Management

• Auto-Generated: When you enable Forwarding, Hookr automatically generates a secure random secret
• Displayed Masked: Shown as XXXX...XXXX (first and last 6 characters visible)
• Copy & Share: Click the copy button and share it with services receiving your webhooks
• Reset Anytime: Click reset to generate a new secret (old secret stops working immediately)
• Treat Like a Password: Never share your secret publicly or commit it to version control

​

Security & Verification

​

Why Verify Signatures?

1. Authenticity — The request actually came from Hookr (not spoofed)
2. Integrity — The payload hasn’t been tampered with during transmission

​

How Signatures Work

​

Verification Methods

1. Body Signature (Recommended) — Verify the HMAC of the entire request body
2. Timestamp Signature — Verify the HMAC of just the timestamp (for GET requests or when body verification isn’t possible)

​

Code Examples: Signature Verification

​

Body Signature Verification

const crypto = require('crypto');

function verifyBodySignature(body, signature, secret) {
  // Extract the hash from the signature header
  const [algorithm, receivedHash] = signature.split('=');
  
  // Calculate expected signature
  const expectedHash = crypto
    .createHmac('sha256', secret)
    .update(body, 'utf8')
    .digest('hex');
  
  // Compare signatures
  return receivedHash === expectedHash;
}

// Usage
const rawBody = request.body; // Raw request body as string
const signature = request.headers['x-hookr-signature'];
const secret = 'your-forward-secret-here';

if (verifyBodySignature(rawBody, signature, secret)) {
  console.log('✅ Signature valid - request is authentic');
} else {
  console.log('❌ Signature invalid - reject request');
}

​

Timestamp Signature Verification

const crypto = require('crypto');

function verifyTimestampSignature(timestamp, signature, secret) {
  const [algorithm, receivedHash] = signature.split('=');
  
  const expectedHash = crypto
    .createHmac('sha256', secret)
    .update(timestamp.toString(), 'utf8')
    .digest('hex');
  
  return receivedHash === expectedHash;
}

// Usage
const timestamp = request.headers['x-hookr-timestamp'];
const signature = request.headers['x-hookr-signature'];
const secret = 'your-forward-secret-here';

if (verifyTimestampSignature(timestamp, signature, secret)) {
  console.log('✅ Timestamp signature valid');
} else {
  console.log('❌ Timestamp signature invalid');
}

​

Best Practices

​

Security

1. Always verify signatures — Never process forwarded events without verifying the signature
2. Treat secrets like passwords — Don’t share them in Slack, email, or commit to version control
3. Rotate secrets periodically — Generate a new secret every 6-12 months
4. Rotate if exposed — If you accidentally leak a secret, reset it immediately
5. Use HTTPS — Always use https:// URLs for forwarding (never http:// in production)
6. Check timestamps — Reject requests with timestamps older than 5 minutes to prevent replay attacks

​

Performance

1. Set timeouts — Configure your external service with reasonable timeouts (Hookr waits 30 seconds maximum)
2. Return quickly — Have your endpoint return a response quickly; do heavy processing asynchronously
3. Monitor forwarding history — Check the Events list to track delivery success rates

​

Testing

1. Test before enabling — Send test events to verify your external service receives and processes them correctly
2. Use local tunneling — Tools like ngrok let you test forwarding to your local development server
3. Check forwarding history — Review response codes and bodies in the event details to debug issues

​

Viewing Forwarding History

​

Where to Find It

1. Open the Events tab in your Hookr app
2. Tap on any event from a webhook with Forwarding enabled
3. Scroll to the Forwarding History section

​

What You See

​

Frequently Asked Questions

​

Does Forwarding work with Private Mode?

​

Can I forward to more than 3 URLs?

​

What happens if one destination fails?

​

Can I see what was forwarded?

​

Does Forwarding cost extra?

​

Can I test Forwarding locally?

​

What if my external service is slow?

​

Can I change the forwarding secret?

​

What HTTP methods are supported?