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

# Automate Knowledge Base Workflows with Nulix Webhooks

> Subscribe to real-time Nulix events and trigger automated workflows in your systems whenever articles or categories are published, updated, or deleted.

Webhooks let you react to events in your Nulix knowledge base the moment they happen. Instead of polling the API for changes, you register an HTTPS endpoint in your own infrastructure and Nulix sends an HTTP POST request to that URL whenever a subscribed event fires. This makes it easy to sync content, send notifications, update downstream systems, or trigger any automated workflow automatically.

## Supported Events

Nulix emits webhook events for the following actions:

| Event | Description |
| - | - |
| `article.published` | Fired when an article is published for the first time or re-published after being taken offline |
| `article.updated` | Fired when the content or metadata of a published article is saved |
| `article.deleted` | Fired when an article is permanently deleted from the knowledge base |
| `category.created` | Fired when a new category is created in the knowledge base |

## Registering a Webhook

**1. Open Webhook Settings**

In your Nulix workspace, go to **Settings > Webhooks**.

**2. Add a New Webhook**

Click **Add Webhook**. Enter the full HTTPS URL of the endpoint in your system that will receive the events.

**3. Select Events**

Choose one or more events to subscribe to. You can subscribe to all events or limit delivery to specific ones.

**4. Save and Test**

Click **Save**. Use the **Send Test Event** button to confirm your endpoint is reachable and responding correctly.

## Registering a Webhook via the API

If you prefer to manage webhooks programmatically — for example, as part of an automated setup script or a multi-tenant integration — you can also register webhook endpoints using the REST API. Send a `POST /webhooks` request with the destination URL and the list of events you want to subscribe to.

```bash theme={null}
curl -X POST https://api.nulix.io/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.example.com/hooks/nulix",
    "events": ["article.published", "article.updated", "article.deleted"]
  }'
```

A successful request returns the new webhook object including its auto-generated `secret`, which you'll use for [signature verification](#verifying-webhook-signatures):

```json theme={null}
{
  "data": {
    "id": "wh_abc123",
    "url": "https://yourapp.example.com/hooks/nulix",
    "events": ["article.published", "article.updated", "article.deleted"],
    "secret": "whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "created_at": "2024-06-10T08:00:00Z"
  }
}
```

> [!NOTE]
>
> Store the `secret` value immediately — Nulix only returns it in the creation response. If you lose it, delete the webhook and create a new one to get a fresh secret.

## Webhook Payload

Every webhook delivery is an HTTP POST request with a JSON body. The payload follows a consistent structure across all event types:

```json theme={null}
{
  "event": "article.published",
  "timestamp": "2024-06-01T10:00:00Z",
  "data": {
    "id": "art_abc123",
    "title": "Getting Started Guide",
    "slug": "getting-started-guide",
    "category_id": "cat_xyz456",
    "published_at": "2024-06-01T10:00:00Z"
  }
}
```

The `event` field identifies what happened, `timestamp` is the UTC time of the event, and `data` contains the resource that was affected.

## Verifying Webhook Signatures

To confirm that a delivery genuinely came from Nulix and not from a third party, verify the `X-Nulix-Signature` header included with every request.

Nulix generates this header by computing an **HMAC-SHA256** hash of the raw request body using your webhook's secret key. To verify it on your end:

**1. Retrieve Your Webhook Secret**

Find the secret for your webhook under **Settings > Webhooks**. Each webhook has its own unique secret.

**2. Compute the Expected Signature**

Using HMAC-SHA256, hash the raw request body with your webhook secret as the key.

**3. Compare the Signatures**

Compare your computed hash to the value in the `X-Nulix-Signature` header. If they match, the delivery is authentic. Reject requests where the signatures do not match.

Here is an example signature verification in Node.js:

```javascript theme={null}
const crypto = require("crypto");

function verifySignature(rawBody, secret, signatureHeader) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}
```

## Retry Policy

If your endpoint does not return a `2xx` HTTP status code, Nulix automatically retries the delivery using exponential backoff:

| Attempt | Delay |
| - | - |
| 1st retry | 1 minute |
| 2nd retry | 5 minutes |
| 3rd retry | 30 minutes |
| 4th retry | 2 hours |
| 5th retry | 8 hours |

After five failed retries, Nulix marks the delivery as permanently failed. You can view the full delivery log — including request and response details — under **Settings > Webhooks > Delivery Logs**.

> [!WARNING]
>
> Your endpoint must respond with an HTTP `200` status within **10 seconds**. If it takes longer, Nulix treats the delivery as failed and initiates the retry sequence. Offload any heavy processing to a background job and return `200` immediately upon receipt.

## Next Steps

Return to the [Integrations Overview](https://docs.nulix.io/integrations/overview.md) to explore other ways to connect Nulix to your tools, or visit [API Access](https://docs.nulix.io/integrations/api-access.md) to query and manage knowledge base content programmatically.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.