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

# Webhook

> Send a signed JSON payload to any HTTP endpoint in real time when a session starts or completes.

The Webhook integration POSTs a signed JSON payload to a URL you control every time an event fires. Use it to build custom automations, connect to internal systems, or bridge to any tool Feedal doesn't have a native integration for.

***

## Setup

1. Go to **Integrations** in the sidebar and click **New integration**.
2. Choose **Webhook**.
3. Fill in the configuration fields and save.
4. Attach the integration to a form from the form's **Connect** tab.

| Field              | Required | Description                                                                             |
| ------------------ | -------- | --------------------------------------------------------------------------------------- |
| **Name**           | Yes      | A label for this webhook (e.g. "Production webhook")                                    |
| **Endpoint URL**   | Yes      | The HTTPS URL that will receive the POST request                                        |
| **HTTP method**    | Yes      | `POST` (default) or `PUT`                                                               |
| **Verify SSL**     | —        | Validate the server's SSL certificate (on by default)                                   |
| **Custom headers** | —        | Additional headers sent with every request — format: `[{"key": "...", "value": "..."}]` |

<Note>
  Private IP addresses and loopback URLs (`127.0.0.1`, `localhost`, `10.x.x.x`,
  etc.) are blocked for security. Your endpoint must be publicly reachable.
</Note>

***

## Payload

Feedal sends a JSON body on every delivery. See [How integrations work](/integrations/overview#payload) for the full payload schema.

**Additional HTTP headers sent with every delivery:**

| Header               | Value                                |
| -------------------- | ------------------------------------ |
| `Content-Type`       | `application/json`                   |
| `User-Agent`         | `Feedal-Webhook/2.0`                 |
| `X-Feedal-Event`     | Event name, e.g. `session.completed` |
| `X-Feedal-Signature` | HMAC-SHA256 signature (see below)    |

***

## Verifying the signature

Every delivery includes an `X-Feedal-Signature` header you can use to confirm the request came from Feedal.

```
X-Feedal-Signature: sha256=<hmac-sha256-hex>
```

Verify it in your server:

```python theme={null}
import hashlib, hmac

def verify_feedal_signature(payload_body: bytes, secret: str, header: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(),
        payload_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, header)
```

```typescript theme={null}
import { createHmac, timingSafeEqual } from "crypto";

function verifyFeedalSignature(body: string, secret: string, header: string): boolean {
  const expected = "sha256=" + createHmac("sha256", secret).update(body).digest("hex");
  return timingSafeEqual(Buffer.from(expected), Buffer.from(header));
}
```

Always use a **timing-safe comparison** (`hmac.compare_digest` / `timingSafeEqual`) to prevent timing attacks.

***

## Finding your secret

The webhook secret is shown once during setup. To view or regenerate it:

1. Open the integration from the **Integrations** page.
2. The **Secret key** field shows the current value.
3. Click **Regenerate secret** to rotate it — update your server immediately after, as old signatures will no longer verify.

***

## Test delivery

Click **Test** on the form integration to fire a test payload immediately. The delivery log shows the response code and latency within seconds.

Feedal considers any HTTP `2xx` response a success. Any other response code — or a connection failure or timeout (10 s) — is recorded as an error.

***

## Next steps

<CardGroup cols={2}>
  <Card title="How integrations work" icon="circle-info" href="/integrations/overview">
    Event model, delivery log, and retry logic.
  </Card>

  <Card title="Developer API" icon="code" href="/developer/api/overview">
    Build a fully custom integration using the REST API.
  </Card>
</CardGroup>