Webhooks

Instead of polling for status, webhooks push events to your server as they happen.

Webhook Delivery Flow

This sequence diagram shows the full lifecycle of a typical content generation integration using webhooks:

How It Works

Select which events to subscribe to when creating the webhook.

Receive events

When an event occurs, Hrizn sends an HTTP POST to your URL with a JSON payload.

Verify the signature

Your server verifies the HMAC-SHA256 signature in the X-Webhook-Signature header.

Process and acknowledge

Process the payload and return a 2xx response. If delivery fails, Hrizn retries with exponential backoff.

Setting Up Webhooks

Via the Dashboard

Go to the API tab in the Dealership Manager, switch to the Webhooks section, and click Add Webhook.

Via the API

curl -X POST https://api.app.hrizn.io/v1/public/webhooks \
  -H "X-API-Key: hzk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/horizn",
    "events": ["content.progress", "content.completed", "ideacloud.completed"]
  }'

const res = await fetch("https://api.app.hrizn.io/v1/public/webhooks", {
  method: "POST",
  headers: {
    "X-API-Key": "hzk_your_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://your-server.com/webhooks/horizn",
    events: ["content.progress", "content.completed", "ideacloud.completed"],
  }),
});
const { data } = await res.json();
// data.secret — store this securely

import requests

response = requests.post(
    "https://api.app.hrizn.io/v1/public/webhooks",
    headers={"X-API-Key": "hzk_your_key_here"},
    json={
        "url": "https://your-server.com/webhooks/horizn",
        "events": ["content.progress", "content.completed", "ideacloud.completed"],
    },
)
data = response.json()["data"]
# data["secret"] — store this securely

$ch = curl_init("https://api.app.hrizn.io/v1/public/webhooks");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        "X-API-Key: hzk_your_key_here",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "url" => "https://your-server.com/webhooks/horizn",
        "events" => ["content.progress", "content.completed", "ideacloud.completed"],
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch));
// $data->data->secret — store this securely

The response includes a secret for verifying signatures.

Store the signing secret in a secrets manager or environment variable. It is returned only once at creation time and cannot be retrieved later.

Event Payload

Every webhook delivery sends a JSON payload:

{
  "id": "evt_1707000000000_abc1234",
  "type": "content.completed",
  "site_id": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "article_id": "a1b2c3d4-...",
    "article_type": "basic"
  },
  "timestamp": "2026-02-10T12:00:00.000Z",
  "api_version": "2025-01-01"
}

Verifying Signatures

Every delivery includes an X-Webhook-Signature header with an HMAC-SHA256 signature of the request body:

X-Webhook-Signature: sha256=abc123def456...

import { createHmac } from "crypto";

function verifyWebhookSignature(body: string, signature: string, secret: string) {
  const expected = createHmac("sha256", secret).update(body).digest("hex");
  return `sha256=${expected}` === signature;
}

// Express middleware
app.post("/webhooks/horizn", (req, res) => {
  const signature = req.headers["x-webhook-signature"];
  const isValid = verifyWebhookSignature(req.rawBody, signature, WEBHOOK_SECRET);

  if (!isValid) {
    return res.status(401).send("Invalid signature");
  }

  const event = JSON.parse(req.rawBody);
  console.log(`Received: ${event.type}`, event.data);

  res.status(200).send("OK");
});

import hmac
import hashlib

def verify_signature(body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    return f"sha256={expected}" == signature

function verifyWebhookSignature(string $body, string $signature, string $secret): bool {
    $expected = hash_hmac("sha256", $body, $secret);
    return "sha256={$expected}" === $signature;
}

// In your webhook handler
$body = file_get_contents("php://input");
$signature = $_SERVER["HTTP_X_WEBHOOK_SIGNATURE"] ?? "";

if (!verifyWebhookSignature($body, $signature, $webhookSecret)) {
    http_response_code(401);
    exit("Invalid signature");
}

$event = json_decode($body, true);
error_log("Received: " . $event["type"]);

http_response_code(200);
echo "OK";

Available Events

IdeaCloud Events

Event	Description	Payload Data
`ideacloud.completed`	IdeaCloud research finished	`ideacloud_id`, `keyword`
`ideacloud.failed`	IdeaCloud research failed	`ideacloud_id`, `keyword`, `error`

Content Events

Event	Description	Payload Data
`content.progress`	Generation stage transition	`article_id`, `article_type`, `component_type`, `stage`, `message`, `progress_percent`
`content.completed`	Content generation finished	`article_id`, `article_type`
`content.failed`	Content generation failed	`article_id`, `article_type`, `error`

Content Approval Events

Event	Description	Payload Data
`content.approval.submitted`	Content submitted for approval	`article_id`, `article_type`, `submitted_by`
`content.approval.approved`	Content approved by reviewer	`article_id`, `article_type`, `approved_by`
`content.approval.rejected`	Content changes requested by reviewer	`article_id`, `article_type`, `rejected_by`, `reason`
`content.approval.escalated`	Content approval escalated to next reviewer	`article_id`, `article_type`, `escalated_to`
`content.approval.overridden`	Content approval overridden by authorized user	`article_id`, `article_type`, `overridden_by`, `reason`

Publishing Events

Event	Description	Payload Data
`content.published`	Content published and available via publish-data endpoint	`article_id`, `article_type`, `posting_status`
`content.unpublished`	Content unpublished (reverted to draft)	`article_id`, `article_type`, `posting_status`
`content.scheduled`	Content scheduled for future publication	`article_id`, `article_type`, `posting_status`

Quality Events

Event	Description	Payload Data
`compliance.completed`	Compliance check finished	`article_id`, `overall_status`, `overall_score`
`content_tools.completed`	Content tools generated	`article_id`, `tools`

Inventory Events

Event	Description	Payload Data
`inventory.description.completed`	Vehicle description generated	`vin`, `year`, `make`, `model`
`inventory.description.batch_completed`	Batch descriptions finished	`count`, `site_id`
`inventory.feed.updated`	Inventory feed refreshed	`vehicle_count`

Event	Description	Payload Data
`social.post.published`	Social post published to one or more platforms	`id`, `status`, `platforms`
`social.post.scheduled`	Social post scheduled for future publication	`id`, `status`, `platforms`
`social.post.failed`	Social post failed to publish	`id`, `status`, `platforms`
`social.review.created`	A new social review was ingested	`review_id`, `platform`, `star_rating`, `location_name`, `account_id`
`social.review.updated`	A social review was updated	`review_id`, `platform`, `star_rating`, `location_name`, `account_id`

Content Progress Events

The content.progress event provides real-time visibility into content generation stages. Unlike terminal events (content.completed, content.failed), progress events fire at meaningful stage transitions — typically 4-6 events per content item.

Stages

Stage	Description	Typical %
`researching`	Vehicle data being fetched (comparisons & model landing pages only)	5%
`outlining`	Article structure being created	5%
`writing`	Content generation started	10-80%
`finalizing`	Post-processing (links, TOC, formatting)	95%

Example Payload

{
  "id": "evt_1707000000000_abc1234",
  "type": "content.progress",
  "site_id": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "article_id": "a1b2c3d4-...",
    "article_type": "comparison",
    "component_type": "Body",
    "stage": "writing",
    "message": "Writing content...",
    "progress_percent": 45
  },
  "timestamp": "2026-02-10T12:00:05.000Z",
  "api_version": "2025-01-01"
}

Subscribers must explicitly include content.progress in their events array when creating or updating a webhook subscription. Existing subscribers only receiving content.completed will not receive progress events unless they update their subscription.

Retry Policy

If your endpoint returns a non-2xx status or times out (15s), Hrizn retries with exponential backoff:

Attempt 1: Immediate
Attempt 2: ~1 minute later
Attempt 3: ~5 minutes later
Attempt 4: ~30 minutes later
Attempt 5: ~2 hours later

After 5 failed attempts, the delivery is sent to a dead letter queue.

After 10 consecutive failures across different events, the webhook subscription is automatically disabled. You’ll need to re-enable it from the dashboard or via PATCH /webhooks/{id}.

Testing

Send a test ping to verify your webhook URL:

curl -X POST https://api.app.hrizn.io/v1/public/webhooks/{id}/test \
  -H "X-API-Key: hzk_your_key_here"

const res = await fetch(
  "https://api.app.hrizn.io/v1/public/webhooks/{id}/test",
  {
    method: "POST",
    headers: { "X-API-Key": "hzk_your_key_here" },
  },
);
const { data } = await res.json();

import requests

response = requests.post(
    "https://api.app.hrizn.io/v1/public/webhooks/{id}/test",
    headers={"X-API-Key": "hzk_your_key_here"},
)
data = response.json()["data"]

$ch = curl_init("https://api.app.hrizn.io/v1/public/webhooks/{id}/test");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ["X-API-Key: hzk_your_key_here"],
    CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch));

This sends a test.ping event to your URL and returns the response status.

Use ngrok or a similar tunneling tool to expose a local development server for testing webhooks without deploying.

Managing Webhooks

Action	Method	Endpoint
Create	`POST`	`/webhooks`
List	`GET`	`/webhooks`
Update	`PATCH`	`/webhooks/{id}`
Delete	`DELETE`	`/webhooks/{id}`
Test	`POST`	`/webhooks/{id}/test`
Deliveries	`GET`	`/webhooks/{id}/deliveries`

Getting Started

Concepts

Guides

Scopes

Webhook Delivery Flow

How It Works

Setting Up Webhooks

Via the Dashboard

Via the API

Event Payload

Verifying Signatures

Available Events

Content Progress Events

Stages

Example Payload

Retry Policy

Testing

Managing Webhooks

​Webhook Delivery Flow

​How It Works

​Setting Up Webhooks

​Via the Dashboard

​Via the API

​Event Payload

​Verifying Signatures

​Available Events

​Content Progress Events

​Stages

​Example Payload

​Retry Policy

​Testing

​Managing Webhooks

Webhook Delivery Flow

How It Works

Setting Up Webhooks

Via the Dashboard

Via the API

Event Payload

Verifying Signatures

Available Events

Content Progress Events

Stages

Example Payload

Retry Policy

Testing

Managing Webhooks