Nuwtonic

https://nuwtonic.com/fr/docs
Admin
Nuwtonic is an agentic SEO and GEO platform that tracks search performance, audits pages, optimizes...
Tokens:27,372
Snippets:235
Trust Score:7.4
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Example target URL

Source: https://nuwtonic.com/fr/docs/webhook-examples

Example target URL used to illustrate how to resolve the slug for a WordPress post or page.

```text
https://example.com/blog/best-ai-seo-tools
```

--------------------------------

### POST /webhooks/nuwtonic

Source: https://nuwtonic.com/fr/docs/webhooks

Example FastAPI endpoint that receives Nuwtonic webhooks, verifies the signature, and routes events to handlers.

```APIDOC
## [POST] /webhooks/nuwtonic

### Description
Receives webhook events from Nuwtonic, verifies the signature, and routes each event to the appropriate handler. It acknowledges completion events and returns a 2xx response.

### Method
POST

### Endpoint
/webhooks/nuwtonic

### Parameters
#### Headers
- **X-ContentKit-Signature** (string) - Required - Signature used to verify the webhook authenticity.
- **X-ContentKit-Timestamp** (string) - Required - Timestamp used in signature verification.

#### Request Body
- **id** (string) - Required - Unique identifier for the webhook event.
- **event** (string) - Required - Type of event (e.g., `content.generated`, `fix.apply`, `fix.generated`).
- **data** (object) - Optional - Event-specific payload.

### Request Example
```json
{
  "id": "evt_65e5d1e6c83d4040",
  "event": "fix.generated",
  "created": 1785059060,
  "data": {
    "job_id": "optimization-job-456",
    "workspace_id": "workspace-id",
    "domain": "cms.example.com",
    "status": "SUCCESS",
    "summary": {
      "total": 1,
      "processed": 1,
      "failed": 0
    },
    "result": {
      "status": "success",
      "id": "fix-operation-456",
      "link": "https://cms.example.com/blog/best-ai-seo-tools"
    }
  }
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the outcome, e.g., `summary_recorded`, `already_processed`, or `completion_recorded`.
- **id** (string) - Identifier of the created or updated article (when applicable).
- **link** (string) - URL of the created or updated article (when applicable).
- **reason** (string) - Reason for ignoring an unsupported event (when applicable).

#### Response Example
```json
{
  "status": "completion_recorded"
}
```

### Error Handling
- **401** - Invalid webhook signature.
- **400** - Webhook event ID is missing.

### Notes
- Completion events (`fix.generated`) are notifications only; record their status and return any 2xx response.
- Unknown events should be acknowledged with a 2xx response to avoid repeated delivery failures.
- The storage and CMS functions in the example are placeholders that must be implemented for your system.
```

--------------------------------

### fix.generated completion event (failed)

Source: https://nuwtonic.com/fr/docs/webhooks

Example of a failed fix.generated completion event. The status is FAILED, summary shows 0 processed and 1 failed, and the result contains an error message. Completion events are notifications only; record their status if needed and return any 2xx response.

```json
{
  "event": "fix.generated",
  "data": {
    "status": "FAILED",
    "summary": {
      "total": 1,
      "processed": 0,
      "failed": 1
    },
    "result": {
      "error": "Webhook returned error status 500"
    }
  }
}
```

--------------------------------

### fix.generated completion event (success)

Source: https://nuwtonic.com/fr/docs/webhooks

Example of a successful fix.generated completion event received on the same URL after a fix.apply request finishes. Contains job_id, workspace_id, domain, status SUCCESS, summary counts, and a result with status, id, and link.

```json
{
  "id": "evt_65e5d1e6c83d4040",
  "event": "fix.generated",
  "created": 1785059060,
  "data": {
    "job_id": "optimization-job-456",
    "workspace_id": "workspace-id",
    "domain": "cms.example.com",
    "status": "SUCCESS",
    "summary": {
      "total": 1,
      "processed": 1,
      "failed": 0
    },
    "result": {
      "status": "success",
      "id": "fix-operation-456",
      "link": "https://cms.example.com/blog/best-ai-seo-tools"
    }
  }
}
```

--------------------------------

### POST /webhooks/nuwtonic

Source: https://nuwtonic.com/fr/docs/webhooks

Documentation for the incoming Nuwtonic webhook that delivers signed JSON events, including a payload example for applying fixes to an existing article.

```APIDOC
## [POST] /webhooks/nuwtonic

### Description
Incoming webhook from Nuwtonic that delivers a signed JSON payload. The receiver must verify the `X-ContentKit-Signature` header using the signing secret. The payload contains an event type and associated data, such as a request to apply fixes to an existing article.

### Method
POST

### Endpoint
Custom receiver URL (provided by Nuwtonic)

### Headers
- **X-ContentKit-Signature** (string) - Required - Signature used to verify the authenticity of the webhook request.

### Request Body
- **id** (string) - Required - Unique identifier of the event.
- **event** (string) - Required - Event type, e.g., `fix.apply`.
- **created** (integer) - Required - Unix timestamp of when the event was created.
- **data** (object) - Required - Payload data containing the target URL and list of fixes.
  - **target_url** (string) - Required - URL of the existing page to update.
  - **fixes** (array) - Required - List of fixes to apply.
    - **type** (string) - Required - Type of fix, e.g., `meta` or `content_replacement`.
    - **location** (string) - Required - Location of the fix, e.g., `<head>` or `Introduction`.
    - **action** (string) - Required - Action to perform, e.g., `replace`.
    - **suggested_value** (string) - Required - New value to apply.
    - **current_value** (string) - Optional - Existing value to validate before replacement (used for content replacement).

### Request Example
```json
{
  "id": "evt_214a2f9bdc294df1",
  "event": "fix.apply",
  "created": 1785059000,
  "data": {
    "target_url": "https://example.com/blog/best-ai-seo-tools",
    "fixes": [
      {
        "type": "meta",
        "location": "<head>",
        "action": "replace",
        "suggested_value": "<title>Best AI SEO Tools for 2026</title>"
      },
      {
        "type": "content_replacement",
        "location": "Introduction",
        "action": "replace",
        "current_value": "Old introduction text.",
        "suggested_value": "Updated introduction text."
      }
    ]
  }
}
```

### Response
#### Success Response (200)
- **id** (string) - ID of the updated page.
- **url** (string) - URL of the updated page.

#### Response Example
```json
{
  "id": "page_123",
  "url": "https://example.com/blog/best-ai-seo-tools"
}
```
```

--------------------------------

### fix.apply webhook payload example

Source: https://nuwtonic.com/fr/docs/webhooks

JSON payload for a fix.apply event that updates an existing article. The workflow must find the page by target_url, validate current_value, update the SEO title, replace the introduction text, save, and return the page ID and URL. It must not create a new post.

```json
{
  "id": "evt_214a2f9bdc294df1",
  "event": "fix.apply",
  "created": 1785059000,
  "data": {
    "target_url": "https://example.com/blog/best-ai-seo-tools",
    "fixes": [
      {
        "type": "meta",
        "location": "<head>",
        "action": "replace",
        "suggested_value": "<title>Best AI SEO Tools for 2026</title>"
      },
      {
        "type": "content_replacement",
        "location": "Introduction",
        "action": "replace",
        "current_value": "Old introduction text.",
        "suggested_value": "Updated introduction text."
      }
    ]
  }
}
```

--------------------------------

### Signed webhook request headers

Source: https://nuwtonic.com/fr/docs/webhooks

Example of the headers included in a signed webhook request. The X-ContentKit-Signature header contains a timestamp parameter t and a v1 parameter with the hexadecimal HMAC-SHA256 signature.

```http
Content-Type: application/json
X-ContentKit-Signature: t=1785058200,v1=<hex-hmac-sha256>
X-ContentKit-Timestamp: 1785058200
```

--------------------------------

### POST Webhook: fix.apply

Source: https://nuwtonic.com/fr/docs/webhooks

Documentation for the webhook event `fix.apply` that delivers optimization fixes to your endpoint.

```APIDOC
## [POST] Webhook: fix.apply

### Description
This webhook event is sent when optimizations are pushed through the webhook integration. Your endpoint receives a payload containing the event details and a list of fixes to apply to a target URL.

### Method
POST

### Endpoint
Your webhook endpoint (as configured in the integration)

### Parameters
#### Request Body
- **id** (string) - Required - Unique identifier of the event.
- **event** (string) - Required - The event type, always `fix.apply`.
- **created** (integer) - Required - Unix timestamp of when the event was created.
- **data** (object) - Required - Contains the target URL, summary, and fixes.
  - **target_url** (string) - Required - The URL of the page or article to apply fixes to.
  - **summary** (object) - Required - Summary of the fixes.
    - **total** (integer) - Required - Total number of fixes.
    - **processed** (integer) - Required - Number of fixes processed.
    - **failed** (integer) - Required - Number of fixes that failed.
  - **fixes** (array) - Required - List of fix objects.
    - **type** (string) - Required - The fix type (e.g., `meta`, `schema`, `content_addition`, `content_replacement`, `structural`, `image_alt`, `internal_link`, `faq`).
    - **location** (string) - Required - Target or placement instruction.
    - **action** (string) - Optional - `before`, `after`, or `replace`. If omitted, treat as `after`.
    - **suggested_value** (string) - Required - The new value to apply.
    - **current_value** (string) - Optional - Value observed during the audit.
    - **location_heading** (string) - Optional - Heading or element hint.
    - **reasoning** (string) - Optional - Explanation for the recommendation.

### Request Example
```json
{
  "id": "evt_214a2f9bdc294df1",
  "event": "fix.apply",
  "created": 1785059000,
  "data": {
    "target_url": "https://cms.example.com/blog/best-ai-seo-tools",
    "summary": {
      "total": 4,
      "processed": 4,
      "failed": 0
    },
    "fixes": [
      {
        "type": "meta",
        "location": "<head>",
        "action": "replace",
        "suggested_value": "<title>Best AI SEO Tools for 2026</title>"
      }
    ]
  }
}
```

### Response
#### Success Response (2xx)
- **id** (string) - Required - Identifier of the fix operation.
- **link** (string) - Required - The URL of the updated resource. `url` is accepted instead of `link`.

#### Response Example
```json
{
  "id": "fix-operation-456",
  "link": "https://cms.example.com/blog/best-ai-seo-tools"
}
```

### Error Handling
Return a non-`2xx` response when the complete operation should be treated as failed. Return `2xx` only after your system has applied or intentionally and safely skipped the fixes.
```

--------------------------------

### POST Webhook URL (content.generated event)

Source: https://nuwtonic.com/fr/docs/webhooks

Documentation for the webhook endpoint that receives content.generated events, including the summary event handling.

```APIDOC
## [POST] Webhook URL (content.generated event)

### Description
This webhook endpoint receives `content.generated` events. The first event indicates that an article has been generated and should be published. A second `content.generated` event, identified by the presence of `data.result.published_count` and `data.result.results`, is a job summary and must not create another article. The endpoint should return a 2xx response for both events.

### Method
POST

### Endpoint
Webhook URL (not specified in source)

### Parameters
#### Request Body
- **id** (string) - Required - Unique event identifier.
- **event** (string) - Required - Event type, e.g., `content.generated`.
- **created** (integer) - Required - Unix timestamp of event creation.
- **data** (object) - Required - Event data payload.
  - **job_id** (string) - Required - Identifier of the publish job.
  - **workspace_id** (string) - Required - Identifier of the workspace.
  - **domain** (string) - Required - Domain associated with the job.
  - **status** (string) - Required - Status of the job, e.g., `SUCCESS`.
  - **summary** (object) - Required - Summary of the job.
    - **total** (integer) - Required - Total number of articles.
    - **processed** (integer) - Required - Number of processed articles.
    - **failed** (integer) - Required - Number of failed articles.
  - **result** (object) - Required - Result of the job.
    - **published_count** (integer) - Optional - Number of published articles. Presence indicates a summary event.
    - **results** (array) - Optional - Array of result objects. Presence indicates a summary event.
      - **keyword** (string) - Required - Keyword associated with the article.
      - **status** (string) - Required - Status of the article, e.g., `published`.
      - **post_id** (string) - Required - Identifier of the published post.
      - **link** (string) - Required - URL of the published article.
      - **category** (string) - Required - Category of the article.
      - **categories** (array of strings) - Required - List of categories.
    - **selected_category** (string) - Optional - Selected category for the job.
    - **selected_categories** (array of strings) - Optional - List of selected categories.

### Request Example
```json
{
  "id": "evt_91ba9852ea9146ab",
  "event": "content.generated",
  "created": 1785058260,
  "data": {
    "job_id": "publish-job-123",
    "workspace_id": "workspace-id",
    "domain": "example.com",
    "status": "SUCCESS",
    "summary": {
      "total": 1,
      "processed": 1,
      "failed": 0
    },
    "result": {
      "published_count": 1,
      "results": [
        {
          "keyword": "best ai seo tools",
          "status": "published",
          "post_id": "cms-post-123",
          "link": "https://cms.example.com/blog/best-ai-seo-tools",
          "category": "SEO",
          "categories": ["SEO"]
        }
      ],
      "selected_category": "SEO",
      "selected_categories": ["SEO"]
    }
  }
}
```

### Response
#### Success Response (2xx)
Any 2xx response is acceptable. The response body is not specified.

#### Response Example
No response body is specified in the source.

### Error Handling
No error handling is specified in the source.
```

--------------------------------

### Apply Safe Fixes Code node

Source: https://nuwtonic.com/fr/docs/webhook-examples

Code node that applies exact content replacements. Requires the previous node to be named `Prepare Target`. Throws errors for unsupported fix types, missing values, or non-unique matches. Add explicit handlers for `meta`, `schema`, `content_addition`, `image_alt`, and FAQ fixes.

```javascript
const source = $("Prepare Target").first().json;
const response = $input.first().json;
const record = Array.isArray(response) ? response[0] : response;

if (!record?.id) {
  throw new Error("No editable CMS page matched data.target_url");
}

let content = record.content?.raw ?? record.content?.rendered ?? "";

const unsupported = source.fixes.filter(
  (fix) => fix.type !== "content_replacement"
);
if (unsupported.length > 0) {
  throw new Error(
    `This example needs handlers for: ${[...new Set(unsupported.map((fix) => fix.type))].join(", ")}`
  );
}

for (const fix of source.fixes) {
  if (!fix.current_value || !fix.suggested_value) {
    throw new Error(
      "content_replacement is missing current_value or suggested_value"
    );
  }

  const occurrences = content.split(fix.current_value).length - 1;
  if (occurrences !== 1) {
    throw new Error(`Expected one exact current_value match; found ${occurrences}`);
  }

  content = content.replace(fix.current_value, fix.suggested_value);
}

return [{
  json: {
    postId: record.id,
    targetUrl: source.targetUrl,
    content,
    fixes: source.fixes
  }
}];

```

--------------------------------

### POST Webhook: content.generated

Source: https://nuwtonic.com/fr/docs/webhooks

Documentation for the content.generated webhook event, including the request payload, required response format, and processing guidelines.

```APIDOC
## [POST] Webhook: content.generated

### Description
This webhook event is sent to your endpoint when a user publishes or saves generated content through the webhook integration. It contains one actionable `content.generated` event per article.

### Method
POST

### Endpoint
Your webhook endpoint (URL configured in Nuwtonic)

### Parameters
#### Request Body
- **id** (string) - Required - Unique event identifier.
- **event** (string) - Required - Event type, always `content.generated`.
- **created** (integer) - Required - Unix timestamp of when the event was created.
- **data** (object) - Required - Contains the job and result details.
  - **job_id** (string) - Required - Identifier for the content generation job.
  - **workspace_id** (string) - Required - Identifier for the workspace.
  - **domain** (string) - Required - Domain associated with the content.
  - **status** (string) - Required - Status of the job, e.g., `SUCCESS`.
  - **summary** (object) - Required - Summary of the job results.
    - **total** (integer) - Required - Total number of articles processed.
    - **processed** (integer) - Required - Number of articles successfully processed.
    - **failed** (integer) - Required - Number of articles that failed.
  - **result** (object) - Required - The generated article record.
    - **id** (string) - Required - Generated article identifier.
    - **keyword** (string) - Optional - Keyword used for generation.
    - **title** (string) - Optional - Title of the article.
    - **slug** (string) - Optional - URL slug for the article. If missing, Nuwtonic may derive it from `keyword`.
    - **status** (string) - Optional - Publication status: `publish` or `draft`.
    - **content** (string) - Optional - Article content (HTML).
    - **content_html** (string) - Optional - Article content in HTML format.
    - **meta_description** (string) - Optional - Meta description for search results.
    - **category** (string) - Optional - Category of the article.
    - **categories** (array of strings) - Optional - List of categories.
    - **schema** (object) - Optional - JSON-LD schema for the article.

### Request Example
```json
{
  "id": "evt_0f1d2c3b4a5e6f70",
  "event": "content.generated",
  "created": 1785058200,
  "data": {
    "job_id": "content-job-001",
    "workspace_id": "workspace-id",
    "domain": "example.com",
    "status": "SUCCESS",
    "summary": {
      "total": 1,
      "processed": 1,
      "failed": 0
    },
    "result": {
      "id": "generated-article-id",
      "keyword": "best ai seo tools",
      "title": "Best AI SEO Tools",
      "slug": "best-ai-seo-tools",
      "status": "publish",
      "content": "<h1>Best AI SEO Tools</h1><p>...</p>",
      "content_html": "<h1>Best AI SEO Tools</h1><p>...</p>",
      "meta_description": "A clear description for search results.",
      "category": "SEO",
      "categories": ["SEO"],
      "schema": {
        "@context": "https://schema.org",
        "@type": "Article"
      }
    }
  }
}
```

### Response
#### Success Response (200)
- **id** (string) - Required - The external resource ID (e.g., CMS post ID).
- **link** (string) - Required - The final article URL. Alternatively, `url` is accepted.

#### Response Example
```json
{
  "id": "cms-post-123",
  "link": "https://cms.example.com/blog/best-ai-seo-tools"
}
```

Alternative response using `url`:
```json
{
  "id": "cms-post-123",
  "url": "https://cms.example.com/blog/best-ai-seo-tools"
}
```

### Notes
- `data.result` is passed through from Nuwtonic, so optional fields can vary by generation workflow. Do not reject the complete event because an optional example field is absent.
- At minimum, your publisher should:
  1. Validate the fields required by your CMS.
  2. Use `result.id` or the event ID as an idempotency key.
  3. Create or update the article.
  4. Respect `result.status`: `publish` makes the article live; `draft` saves it without making it live.
  5. Store and return the final CMS ID and article URL.
- If `slug` is missing, Nuwtonic may derive it from `keyword`, but your system should still validate it before publishing.
- Always return the real article URL. Responses without `link` or `url` cannot reliably identify the published article.
```

--------------------------------

### POST /api/v1/rest

Source: https://nuwtonic.com/fr/docs/webhooks

Documentation for calls from an HTTP module to the Nuwtonic REST API, specifying the required authentication header.

```APIDOC
## [POST] /api/v1/rest

### Description
Calls from an HTTP module to the Nuwtonic REST API. Authentication is performed using a Bearer token in the Authorization header. Do not use `X-API-Key`.

### Method
POST

### Endpoint
Nuwtonic REST API endpoint (exact path not specified in source)

### Headers
- **Authorization** (string) - Required - Bearer token with the format `Bearer <api_key>`.

### Request Body
(Not specified in source)

### Response
(Not specified in source)
```

--------------------------------

### Single-endpoint webhook routing with FastAPI

Source: https://nuwtonic.com/fr/docs/webhooks

FastAPI endpoint that handles all webhook events on a single route. Verifies the signature using X-ContentKit-Signature and X-ContentKit-Timestamp headers, checks for duplicate event IDs, and routes content.generated, fix.apply, and fix.generated events. Unknown events are acknowledged and logged. The storage and CMS functions are placeholders that must be implemented.

```python
from fastapi import FastAPI, HTTPException, Request

app = FastAPI()
WEBHOOK_SECRET = "replace-with-the-configured-secret"


@app.post("/webhooks/nuwtonic")
async def nuwtonic_webhook(request: Request):
    raw_body = await request.body()
    signature = request.headers.get("X-ContentKit-Signature", "")
    timestamp = request.headers.get("X-ContentKit-Timestamp", "")

    if not verify_webhook(raw_body, signature, timestamp, WEBHOOK_SECRET):
        raise HTTPException(status_code=401, detail="Invalid webhook signature")

    payload = await request.json()
    event_id = payload.get("id")
    event = payload.get("event")
    data = payload.get("data") or {}

    if not event_id:
        raise HTTPException(status_code=400, detail="Webhook event ID is missing")

    if await event_was_processed(event_id):
        return {"status": "already_processed"}

    if event == "content.generated":
        result = data.get("result") or {}

        if "published_count" in result and "results" in result:
            await record_publish_summary(payload)
            await mark_event_processed(event_id)
            return {"status": "summary_recorded"}

        post = await publish_or_update_article(result)
        await mark_event_processed(event_id)
        return {"id": post.id, "link": post.url}

    if event == "fix.apply":
        operation = await apply_fixes(
            target_url=data.get("target_url"),
            fixes=data.get("fixes") or [],
        )
        await mark_event_processed(event_id)
        return {"id": operation.id, "link": operation.url}

    if event == "fix.generated":
        await record_fix_completion(payload)
        await mark_event_processed(event_id)
        return {"status": "completion_recorded"}

    # Acknowledge unknown notification events so future additions do not
    # create repeated delivery failures. Log them for later review.
    await record_unknown_event(payload)
    await mark_event_processed(event_id)
    return {"status": "ignored", "reason": "unsupported_event"}
```

--------------------------------

### Print JSON-LD schema metafields in theme.liquid

Source: https://nuwtonic.com/fr/docs/shopify

Place inside the <head> of theme.liquid before the closing </head> tag to output JSON-LD schema stored in page and article metafields. Without this snippet, metafield values may be saved but visitors will not see the JSON-LD in page source.

```liquid
{% if page.metafields.seo.json_ld_schema %}
<script type="application/ld+json">
{{ page.metafields.seo.json_ld_schema }}
</script>
{% endif %}

{% if article.metafields.seo.json_ld_schema %}
<script type="application/ld+json">
{{ article.metafields.seo.json_ld_schema }}
</script>
{% endif %}

```

--------------------------------

### n8n node order for publishing an article

Source: https://nuwtonic.com/fr/docs/webhook-examples

Recommended node order for the n8n workflow that publishes an article. The Webhook receives the Nuwtonic payload, the Switch routes events, the WordPress or HTTP Request node performs the CMS action, and Respond to Webhook returns the result.

```text
Webhook → Switch → WordPress/HTTP Request → Respond to Webhook

```

--------------------------------

### Webhook integration configuration

Source: https://nuwtonic.com/fr/docs/webhooks

Configure the webhook integration with a nested webhook object. The url is the public HTTPS endpoint receiving every event, secret is generated by Nuwtonic and signs each request with HMAC-SHA256, and enabled controls delivery; when false, publishing and fix application are skipped.

```json
{
  "webhook": {
    "url": "https://cms.example.com/webhooks/nuwtonic",
    "secret": "generated-by-nuwtonic",
    "enabled": true
  }
}
```

--------------------------------

### Prepare Target Code node

Source: https://nuwtonic.com/fr/docs/webhook-examples

Code node that extracts the target URL and fixes from the webhook payload. Requires the Webhook node to be named `Nuwtonic Webhook`. Throws an error if `target_url` or `data.fixes` is missing.

```javascript
const payload = $("Nuwtonic Webhook").first().json.body
  ?? $("Nuwtonic Webhook").first().json;

const target = new URL(payload.data.target_url);
const slug = target.pathname.split("/").filter(Boolean).pop();

if (!slug || !Array.isArray(payload.data.fixes) || payload.data.fixes.length === 0) {
  throw new Error("fix.apply is missing target_url or data.fixes");
}

return [{
  json: {
    eventId: payload.id,
    targetUrl: payload.data.target_url,
    slug,
    fixes: payload.data.fixes
  }
}];

```
Tokens:
Raw