# Security Layer

## Introduction

Security is paramount in webhook processing. Webhooked provides multiple authentication mechanisms to ensure only authorized sources can trigger your webhooks.

## Security Context Variables

Variables available in security conditions:

| Variable             | Description                                            | Example                                   |
| -------------------- | ------------------------------------------------------ | ----------------------------------------- |
| `.SpecName`          | Name of the current spec as defined in config          | `"user-events"`                           |
| `.SpecEntrypointURL` | EntrypointURL of the current spec as defined in config | `"/user-events"`                          |
| `.ConnID`            | Unique connection ID                                   | `123549841`                               |
| `.ConnTime`          | Connection established time                            | time.Time object `2025-08-20T21:10:00Z`   |
| `.Host`              | Host header of request                                 | `"example.com"`                           |
| `.IsTLS`             | Whether request is HTTPS                               | `true`                                    |
| `.Method`            | HTTP method used                                       | `"POST"`                                  |
| `.Payload`           | Raw request body                                       | `{"data": "value"}`                       |
| `.QueryArgs`         | Query parameters object                                | `fasthttp.Args{"id":"123","token":"abc"}` |
| `.RemoteAddr`        | Remote Addr                                            | `"192.168.1.10:54321"`                    |
| `.RemoteIP`          | Remote network address                                 | `"192.168.1.1"`                           |
| `.RequestTime`       | Time when request was received                         | time.Time object `2025-08-20T21:10:00Z`   |
| `.Request`           | Full `fasthttp.Request` object                         | `&fasthttp.Request{...}`                  |
| `.URI`               | Request URI                                            | `"/webhooks/..."`                         |
| `.UserAgent`         | Client User-Agent header                               | `"Mozilla/5.0 (X11; Linux x86_64)"`       |

## Security Providers

### GitHub

The GitHub provider validates webhook signatures using HMAC-SHA256.

```yaml
security:
  type: github
  specs:
    secret: # Valuable - see doc "Sourcing (Valuable)" for more info
      valueFrom:
        envRef: GITHUB_WEBHOOK_SECRET
```

#### How It Works

1. GitHub signs the payload with your secret using HMAC-SHA256
2. Sends signature in `X-Hub-Signature-256` header
3. Webhooked validates the signature matches
4. Rejects with 401 if validation fails

#### GitHub Webhook Setup

In your GitHub repository settings:

1. Go to Settings → Webhooks
2. Add webhook URL: `https://your-domain/webhooks/v1alpha2/your-path`
3. Set Content type: `application/json`
4. Set Secret: Your webhook secret
5. Select events to trigger webhook

#### Validation Example

```yaml
webhooks:
  - name: github-push
    entrypointUrl: /github/push
    security:
      type: github
      specs:
        secret:
          valueFrom:
            envRef: GITHUB_SECRET
    response:
      statusCode: 200
      formatting:
        templateString: |
          {
            "status": "validated",
            "event": "{{ .Request.Header.Peek "X-GitHub-Event" | toString }}",
            "delivery": "{{ .Request.Header.Peek "X-GitHub-Delivery" | toString }}"
          }
```

### Custom

The custom provider allows you to define authentication logic using Go templates.

#### Basic Token Authentication

```yaml
security:
  type: custom
  specs:
    condition: |
      {{ eq (.Request.Header.Peek "X-API-Key" | toString) (env "API_KEY") }}
```

#### Multiple Conditions

```yaml
security:
  type: custom
  specs:
    condition: |
      {{ and 
        (eq (.Request.Header.Peek "X-API-Key" | toString) (env "API_KEY"))
        (eq (.Request.Header.Peek "X-Tenant-ID" | toString) "tenant-123")
        (contains (.Request.Header.Peek "User-Agent" | toString) "MyApp")
      }}
```

### NoOp

The NoOp provider disables authentication entirely. **Use only in development!**

```yaml
security:
  type: noop
```

⚠️ **Warning**: Never use `noop` in production environments!


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.atom.codes/webhooked/configuration/security-layer.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.