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

# Developer Tools

> Manage your API token and configure webhooks to integrate Cernel into your own systems.

Developer Tools give you programmatic access to Cernel. Use the API to push products from your own systems, and set up webhooks to receive real-time notifications when enrichment completes.

## How it works

Cernel provides two developer capabilities under **Settings > Developer**:

* **API** lets you authenticate requests to the [Public API](/integrations/public-api) using a unique token tied to your organization.
* **Webhooks** send HTTP POST notifications to your endpoints whenever key events happen in Cernel.

### Why you would use this

<CardGroup cols={2}>
  <Card title="Automate product syncing" icon="rotate">
    Push products from your ERP, PIM, or custom backend into Cernel without manual imports.
  </Card>

  <Card title="React to enrichment in real time" icon="bolt">
    Get notified the moment AI-generated content is ready, so your systems can pull and publish it automatically.
  </Card>
</CardGroup>

## Step-by-step guide

### Managing your API token

<Steps>
  <Step title="Open API settings">
    Go to **Settings > API**. You'll see your API token (masked by default), the last refresh date, and a link to the API documentation.
  </Step>

  <Step title="Copy your token">
    Click the copy icon next to the token field to copy it to your clipboard. Click **Show** to reveal the full token if you need to verify it.

    <Tip>
      Store your API token securely. Treat it like a password. Anyone with this token can access your organization's data through the API.
    </Tip>
  </Step>

  <Step title="Refresh your token (if needed)">
    Click **New key** to generate a new token. A confirmation dialog will warn you that the current token will stop working immediately.

    <Warning>
      Generating a new key invalidates the previous one. Any integrations using the old token will break until you update them with the new one.
    </Warning>
  </Step>

  <Step title="View API documentation">
    Click **Visit Documentation** to open the full API reference in a new tab. This includes all available endpoints, request formats, and response schemas.
  </Step>
</Steps>

### Configuring webhooks

<Steps>
  <Step title="Open webhook settings">
    Go to **Settings > Webhooks**. You'll see three webhook types, each with a URL field and a test button.
  </Step>

  <Step title="Enter your endpoint URL">
    For each webhook you want to enable, enter the URL where Cernel should send POST requests. The URL must start with `http://` or `https://`.
  </Step>

  <Step title="Test the webhook">
    Click **Test Webhook** to send a sample payload to your endpoint. Cernel will confirm whether the test succeeded or failed.

    <Check>
      If the test succeeds, your endpoint is correctly configured and ready to receive live events.
    </Check>
  </Step>
</Steps>

## Webhook event types

Cernel supports three webhook events:

| Event                | When it fires                                          | Use case                                                      |
| -------------------- | ------------------------------------------------------ | ------------------------------------------------------------- |
| **Attribute Result** | An AI-generated attribute value is ready for a product | Trigger downstream processing as soon as content is generated |
| **Product Updated**  | A product is updated with enriched content             | Sync updated product data to your store or PIM                |
| **Product Created**  | A new product is created in Cernel                     | Keep external systems in sync when products arrive            |

Each webhook sends a POST request with the event data as a JSON payload to your configured URL.

## Advanced configuration

<AccordionGroup>
  <Accordion title="Using webhooks with the API pipeline">
    Webhooks pair naturally with the [Public API integration](/integrations/public-api). Push products in via API, let automations enrich them, then receive webhook notifications when results are ready. See [Building a custom product pipeline](/integrations/public-api#building-a-custom-product-pipeline) for a full walkthrough.
  </Accordion>

  <Accordion title="Webhook reliability">
    If your endpoint returns an error or is unreachable, Cernel automatically retries the delivery. Each event is attempted up to **8 times**: the first retry follows about 5 seconds after the initial failure, and the delay grows with each subsequent attempt, so the final retries are spread over a longer window. A delivery is considered successful once your endpoint returns a 2xx status code.

    <Tip>
      Because the same event can be delivered more than once, design your endpoint to be **idempotent**: processing the same payload twice should be safe. Use the IDs in the payload (for example the job or product identifier) to detect and skip duplicates.
    </Tip>
  </Accordion>

  <Accordion title="Verifying webhook authenticity">
    Every webhook Cernel sends includes an **`X-Signature-SHA256`** header so you can confirm the request genuinely came from Cernel and wasn't altered in transit. The signature is an HMAC-SHA256 of the request body, keyed on your API token (the same token from **Settings > API**).

    To verify a request:

    <Steps>
      <Step title="Re-serialize the payload">
        Serialize the received JSON body the same way Cernel does: with sorted keys and compact separators (no spaces). In Python: `json.dumps(payload, separators=(",", ":"), sort_keys=True)`.
      </Step>

      <Step title="Compute the HMAC">
        Compute an HMAC-SHA256 over that serialized body, using your API token as the secret key, then Base64-encode the result.
      </Step>

      <Step title="Compare">
        Compare your computed value against the `X-Signature-SHA256` header. If they match, the request is authentic. Reject the request if they differ.
      </Step>
    </Steps>

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

    def is_valid(raw_body: bytes, signature_header: str, api_token: str) -> bool:
        payload = json.loads(raw_body)
        canonical = json.dumps(payload, separators=(",", ":"), sort_keys=True).encode("utf-8")
        expected = base64.b64encode(
            hmac.new(api_token.encode(), canonical, hashlib.sha256).digest()
        ).decode()
        return hmac.compare_digest(expected, signature_header)
    ```

    <Tip>
      The signature depends on an exact byte-for-byte match of the serialization. Any difference in spacing or key ordering produces a different signature, so re-serialize with sorted keys and compact separators before comparing.
    </Tip>
  </Accordion>

  <Accordion title="Security considerations">
    Webhook URLs are stored in your organization settings. Only admin users can view or modify them. Always serve your webhook endpoint over HTTPS, verify the `X-Signature-SHA256` header on every request (see above), and keep the endpoint behind authentication on your end to prevent unauthorized requests.
  </Accordion>
</AccordionGroup>

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Where do I find my API token?">
    Go to **Settings > API**. Your token is displayed there (masked by default). Click **Show** to reveal the full value, or click the copy icon to copy it.
  </Accordion>

  <Accordion title="Can I have multiple API tokens?">
    No. Each organization has one API token at a time. Refreshing generates a new token and invalidates the previous one.
  </Accordion>

  <Accordion title="Why isn't my webhook receiving events?">
    Check that your URL is correct and reachable. Use the **Test Webhook** button to verify. Make sure your endpoint returns a 2xx status code. If the test succeeds but live events don't arrive, confirm that the relevant actions (enrichment, product creation) are actually happening.
  </Accordion>

  <Accordion title="Can I configure webhooks for other events?">
    Currently, Cernel supports three webhook events: Attribute Result, Product Updated, and Product Created. More event types may be added in future updates.
  </Accordion>
</AccordionGroup>

## What's next

<CardGroup cols={2}>
  <Card title="Public API" icon="arrow-right" href="/integrations/public-api">
    Set up a full API integration for pushing products programmatically.
  </Card>

  <Card title="Automations" icon="arrow-right" href="/features/automations">
    Auto-enrich products pushed via API with automations.
  </Card>
</CardGroup>