> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hookflo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Security Overview

> Learn about HookFlo's comprehensive security features and algorithm-agnostic payload processing

HookFlo is built with security as a fundamental principle. This guide outlines our approach to securing webhook communication, protecting sensitive data, and ensuring the integrity of all webhook events processed through our platform.

<Note>
  Security is a shared responsibility. While HookFlo provides robust security features, it's important to follow best practices when configuring your webhooks and handling sensitive data.
</Note>

## Core Security Features

### Webhook Authentication & Verification

HookFlo supports multiple methods for authenticating and verifying webhook sources:

<CardGroup cols={2}>
  <Card title="HMAC Signature Verification" icon="shield-check">
    Verify the authenticity of webhooks using HMAC signatures with algorithms like SHA-256
  </Card>

  <Card title="JWT Validation" icon="key">
    Validate JSON Web Tokens using various signing algorithms
  </Card>

  <Card title="API Keys" icon="lock">
    Implement simple key-based authentication for webhook sources
  </Card>

  <Card title="Basic Authentication" icon="user-lock">
    Support for username/password verification methods
  </Card>
</CardGroup>

<CodeGroup>
  ```json HMAC Configuration
  {
    "verification": {
      "type": "hmac",
      "algorithm": "sha256",
      "signatureHeader": "X-Hub-Signature-256",
      "signaturePrefix": "sha256=",
      "secret": "${WEBHOOK_SECRET}"
    }
  }
  ```

  ```json JWT Configuration
  {
    "verification": {
      "type": "jwt",
      "algorithm": "RS256",
      "secret": "${JWT_PUBLIC_KEY}",
      "claimValidation": {
        "iss": "api.service.com",
        "aud": "hookflo"
      }
    }
  }
  ```
</CodeGroup>

HookFlo verifies signatures using the exact algorithm specified by the webhook provider, ensuring compatibility with any service.

## Algorithm-Agnostic Payload Processing

HookFlo is designed to work with any webhook format or encoding scheme used by service providers.

Our platform handles various encoding formats:

| Encoding Type   | Description                                          | Use Case                                                  |
| --------------- | ---------------------------------------------------- | --------------------------------------------------------- |
| Base64          | Decodes Base64-encoded payloads (standard, URL-safe) | Services that encode binary data or compress payloads     |
| URL Encoding    | Parses URL-encoded request bodies                    | Form submissions and legacy webhook systems               |
| JWT Payload     | Extracts and validates claims from JWT tokens        | Modern API systems using token-based authentication       |
| Gzip/Deflate    | Automatically decompresses compressed payloads       | High-volume webhook systems that optimize for size        |
| Custom Encoding | Apply custom decoding functions                      | Proprietary encoding formats unique to specific providers |

Multiple decoding steps can be chained to handle complex encoding schemes:

```json
{
  "preProcessing": {
    "decoding": [
      {
        "type": "base64",
        "target": "body.data"
      },
      {
        "type": "gzip",
        "target": "decodedData"
      }
    ]
  }
}
```

### Comprehensive Algorithm Support

HookFlo supports all commonly used signature verification algorithms:

<CardGroup cols={3}>
  <Card title="HMAC Algorithms" icon="lock-hashtag">
    <ul>
      <li>HMAC-SHA256</li>
      <li>HMAC-SHA1</li>
      <li>HMAC-SHA384/512</li>
      <li>HMAC-MD5 (legacy)</li>
    </ul>
  </Card>

  <Card title="Asymmetric Algorithms" icon="key-skeleton">
    <ul>
      <li>RSA-SHA256</li>
      <li>ECDSA</li>
      <li>EdDSA (Ed25519)</li>
    </ul>
  </Card>

  <Card title="JWT Algorithms" icon="token">
    <ul>
      <li>HS256, HS384, HS512</li>
      <li>RS256, RS384, RS512</li>
      <li>ES256, ES384, ES512</li>
      <li>PS256, PS384, PS512</li>
    </ul>
  </Card>
</CardGroup>

New algorithms are continuously added to maintain compatibility with all webhook providers.

### Verification Methods

<Accordion title="Flexible Verification Strategies">
  Different services implement webhook verification in various ways:

  #### Header-Based Signatures

  * Standard header placement
  * Custom header names
  * Multiple signature headers

  #### Request Parameter Verification

  * Query parameter signatures
  * Form-encoded signatures
  * Timestamp-based verification

  #### Body Hash Verification

  * Complete body hashing
  * Canonicalized JSON
  * Specific field selection

  HookFlo's verification engine can be configured to match any provider's approach, ensuring you can securely process webhooks from any service.
</Accordion>

## Best Practices

### Security Checklist

<Check>
  * Enable signature verification for all webhook sources
  * Implement IP allowlisting for known webhook providers
  * Redact sensitive data fields using JSON path selectors
  * Set appropriate retention periods for webhook data
  * Configure webhook timeout settings to prevent hanging connections
  * Regularly rotate webhook secrets and API keys
  * Monitor the webhook security audit log for suspicious activity
  * Use rate limiting to protect endpoints from abuse
  * Implement strict CORS policies for web-based webhook endpoints
</Check>

### Security Recommendations

<Accordion title="For Public-Facing Endpoints">
  * Always enable signature verification
  * Implement rate limiting and IP filtering
  * Use HTTPS with modern TLS settings
  * Consider adding CAPTCHA for user-initiated webhooks
  * Monitor for unusual traffic patterns
</Accordion>

<Accordion title="For Internal Systems">
  * Use mutual TLS (mTLS) for service-to-service communication
  * Implement network-level isolation for webhook processing systems
  * Consider using private endpoints within your network
  * Implement strict egress filtering for webhook consumers
</Accordion>

Need Support? [Let us know](mailto:support@hookflo.dev)\
or [DM me directly on X](https://x.com/Prateek53788134).