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

# n8n Webhooks & Events

This page explains how to trigger workflows and interact with Sitecopilot in near‑real‑time.

## How Sitecopilot modules use webhooks

Sitecopilot modules can **call webhooks** to interact with your n8n workflows. This enables custom processing without server‑side changes.

### Contact Form module → n8n webhook

The **Contact Form** module lets you configure an **n8n Webhook URL**. Every submission is sent as **JSON** to that URL.

* **Where to set it**: in the form module settings, set the **Webhook URL** field to your n8n webhook endpoint (e.g., `https://n8n.example.com/webhook/sitecopilot-contact` or test URL `.../webhook-test/...`).
* **Payload shape (example)**:

```json theme={null}
{
"module": "contact-form",
"form_id": "contact-main",
"submitted_at": "2025-09-15T10:32:00Z",
"page_url": "/contact",
"locale": "fr",
"fields": {
"name": "Jane Doe",
"email": "jane@example.com",
"message": "Hello!"
},
"metadata": {
"ip": "203.0.113.10",
"user_agent": "Mozilla/5.0 ..."
}
}
```

* **What you can do**: create CRM leads, send emails, post to Slack, validate & enrich, trigger AI workflows, etc.

> Virtually any scenario is possible: n8n receives JSON, you chain nodes as needed.

### Recommended webhook security

* Use a **secret** in the path or a **shared header** (e.g., `X-Webhook-Signature`) checked in n8n **Code** node.
* Prefer HTTPS only; rate‑limit if your gateway supports it.
* Return `2xx` from n8n to acknowledge receipt; retry on 5xx.

## Triggers in n8n

* **Webhook (incoming)** — accept POST/GET and then call Sitecopilot as needed.
* **Cron / Interval** — poll Sitecopilot endpoints on a schedule (e.g., nightly content updates).
* **Manual / UI Button** — run ad‑hoc maintenance jobs.

## Examples

### Publish content on incoming webhook

1. **Webhook** node (POST): receives `{ "url": "api", "templates": [ ... ] }`
2. **HTTP Request** node → `PUT {{$env.SITECOPILOT_TENANT_BASE_URL}}/api/content`

* Header: `Authorization: Bearer {{$env.SITECOPILOT_TENANT_TOKEN}}`
* Body: JSON from the webhook

3. **HTTP Request** node (optional) → `POST /api/notifications`

### Nightly sitemap snapshot (polling)

1. **Cron** node: `0 3 * * *`
2. **HTTP Request** → `POST {{$env.SITECOPILOT_TENANT_BASE_URL}}/api/sitemap`
3. **Write Binary File** (or Drive) to persist the JSON with a timestamped filename.

### Asset ingestion pipeline

1. **S3/Drive** trigger → file path
2. **HTTP Request** (multipart) → `POST /api/asset`
3. Store returned URL in your content schema; follow with **PUT /api/content\`** if needed.

## Reliability

* Validate payloads before calling Sitecopilot.
* Use **error branches** and alerting (e.g., Slack) for 4xx/5xx.
* Add **retry** with exponential backoff on transient failures.