Webhooks

Webhooks send an HTTP POST to your endpoint when something happens in your HCTI organization. Use them to publish content after an image reaches storage, keep your application in sync with template changes, or notify your team about usage.

Choose the events each endpoint receives, add headers or query parameters for your receiving service, and enable signatures to verify deliveries. The dashboard records event payloads and delivery attempts.

1. Open Webhooks in the dashboard and click Add webhook. Owners and Admins can manage webhooks. Users can view them and their delivery history.
2. Enter a Name and Endpoint URL, such as https://hooks.example.com/hcti. Use a public HTTPS endpoint with a DNS hostname on the default HTTPS port. Add query parameters separately rather than including them in this URL.
3. Under Events to receive, expand the groups and select the events your application needs. For example, select image_stored to act when rendered files have been saved.
4. If your receiver needs authentication or routing values, click Add parameter, choose Header or Query, and enter its name and value. Mark credentials Secret to encrypt them and hide them from later views and delivery history.
5. Turn on Sign deliveries to add signature verification. Clear Enabled and click Save so you can configure verification before the first delivery.
6. Open Edit webhook, then Reveal signing secret, and copy it into your receiving application’s server-side configuration. The secret is generated for every webhook, including those created through the API, and is revealed only in the dashboard.
7. Once your receiver is ready, select Enabled and Save. This queues a webhook_test delivery using your configured parameters and signing setting.

Creating an enabled webhook also queues a webhook_test delivery automatically. Your receiver should accept this event even if it only acts on a particular business event.

The webhook list also provides Send a test event, Edit webhook, View delivery history, and Delete webhook actions. Each enabled webhook accepts one test every 30 seconds. Your organization can make five manual test requests per minute.

Webhooks receive matching events while enabled. Adding a subscription does not replay earlier resource changes or already-stored images.

Free plans include up to 2 webhooks per organization. Paid plans include 10. Disabled webhooks still count toward that limit.

Use POST /v1/webhooks with webhooks:create_update and read access to the resources you subscribe to. For example, an image-storage subscription also needs images:read:

curl 'https://hcti.io/v1/webhooks' \
  --user "$HCTI_API_ID:$HCTI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Image publishing",
    "url": "https://hooks.example.com/hcti",
    "disabled": true,
    "events": ["image_stored"],
    "signing_enabled": true
  }'

This creates a disabled webhook, so test_event_id is null and nothing is sent yet. Signed setup through REST or MCP includes a dashboard step: open Edit webhook → Reveal signing secret, then store the secret in your receiver’s server-side configuration. Signing secrets and secret parameter values are never returned by REST or MCP.

Once your receiver is ready, enable the webhook in the dashboard, or send the complete configuration to POST /v1/webhooks/WEBHOOK_ID with disabled: false. Keep signing_enabled: true and include every subscription and parameter you want to retain. Updates replace the configuration rather than patching individual fields. Enabling queues a webhook_test and returns its test_event_id without waiting for successful delivery.

See the Webhooks API for replacement updates, secret retention, test requests, and event lookup. The MCP webhook tools support the same operations. MCP connections cannot subscribe to API key events because they cannot grant api_keys:read.

Every POST has Content-Type: application/json and the same outer object, or envelope. The envelope identifies the event. Its data field contains the payload for that event’s type.

{
  "event_id": "example_event_id",
  "type": "image_stored",
  "schema_version": 1,
  "occurred_at": "2026-10-29T14:00:00Z",
  "source": {
    "channel": "api",
    "api_id": "your-api-id",
    "ip": "203.0.113.10",
    "user_agent": "my-image-service/1.0"
  },
  "data": {
    "image_id": "01a135fb-21fa-7027-9b82-70acc0e1fd16",
    "width": 1200,
    "height": 630,
    "file_size_bytes": 48210,
    "location": "hcti_storage",
    "location_details": null
  }
}

Templates, proxies, storage destinations, Open Graph configurations, and API keys share three event patterns. Each uses the envelope above, with an entity object inside data identifying the resource by its type and id.

For example, template_created and proxy_created have the same outer structure but different properties. Update events use dotted paths for nested properties. A request that leaves all public properties unchanged does not produce an update event.

Each entry in changes has a kind that describes how to read it:

Image, organization, and test events have their own data shapes. For example, image_deleted contains image_ids rather than an entity object. See the event definitions for each payload.

Stored passwords, API key secrets, storage secret access keys, and webhook signing secrets are never included in event payloads. Public identifiers such as api_id and a storage access_key_id can be included to identify the key or connection.

Creation events report credential state through flags such as password_assigned and secret_access_key_assigned. Update events use kind: "secret" with previous_assigned and new_assigned. Replacing an existing password reports true for both flags without including either password.

Large text values such as html and css may be truncated to keep payloads small. These fields use a text object rather than a plain string, including when they appear as previous_value or new_value in an update:

When truncated is true, fetch the resource if you need its full current content. A block template’s internal design is reported as a content change without its contents.

Use webhook-id to deduplicate a delivery at one receiver. If multiple endpoints feed the same workflow, you can use the envelope’s event_id to deduplicate the event across those endpoints. Store the deduplication record atomically with accepting or processing the event so simultaneous deliveries cannot both start the same work.

Turn on Sign deliveries and use the webhook’s signing secret to verify the raw request body before parsing it. Standard Webhooks verifier libraries can check these headers. Re-serializing JSON can change whitespace or property order and invalidate the signature.

The signature is an HMAC-SHA256 of:

webhook-id.webhook-timestamp.raw-request-body

Strip the whsec_ prefix from the signing secret and base64-decode the remainder to obtain the HMAC key. Compare signatures in constant time and reject stale timestamps to limit replay. A retry has a fresh timestamp and signature but retains its delivery ID.

The runnable Node.js receiver below verifies the original request bytes and accepts timestamps within five minutes of the server’s clock. Keep the secret in server-side configuration. Use the verified envelope’s event_id and data when deciding what work to perform.

HCTI uses at-least-once delivery: your receiver must be able to accept the same event more than once. Event recording and HTTP delivery are separate, so an unavailable receiver does not roll back the change.

These recording rules apply to matching subscriptions. They do not replay changes from before a webhook was enabled.

At-least-once does not mean unlimited retries or guaranteed success at an unreachable endpoint. Delivery can end in failure after its retry window, or be invalidated when a webhook is disabled, deleted, or unsubscribed. An HTTP request may reach your application even if its response is lost, causing another attempt.

A delivery gets up to 5 automatic attempts in total: the initial attempt, then retries after approximately 5 minutes, 1 hour, 12 hours, and 2 days, each measured from the previous failed attempt. Retry-After can delay the next attempt further but does not add attempts. No attempt is scheduled beyond 3 days after the event occurred. An endpoint has about 10 seconds to respond.

There is currently no manual retry or replay action in the dashboard, REST API, or MCP. Once a delivery reaches final failure or its retry window ends, fixing your endpoint does not resend that event. Sending a test checks the endpoint with a new webhook_test event. It does not replay the failed business event.

Use delivery history to identify failed events and inspect their payloads. Reconcile your application’s state with the current image or resource, then enqueue any missing work in your own system. If you recover a historical payload, use its original event_id in the same deduplication path as normal deliveries. Keep a durable inbox of received events so you can retry your own processing independently of HCTI’s delivery window.

1. Verify the signature and parse the envelope.
2. Durably accept the event, using a unique delivery or event ID to prevent duplicate processing. Acknowledge known duplicates with 2xx too.
3. Return 2xx promptly, then perform longer work from your own queue. If you cannot durably accept the event, return a retryable error such as 503.
4. Make downstream actions idempotent as well, so restarting a worker does not publish the same post or send the same email twice.

Events can arrive concurrently and out of order. Retries of older events can arrive after newer changes. Use event timestamps and resource versions where available. Fetch the current resource if your workflow needs its latest state. An update payload describes that change, not necessarily the state at the time you receive it.

This example uses Node.js 24 and its built-in SQLite module. It verifies signed POST requests at /hcti, commits each event to a durable inbox, and returns 204 for accepted events and known duplicates. It also accepts webhook_test, marking it processed without starting business work. A failed database write returns 503 so HCTI can retry.

Download webhook-receiver.mjs, set HCTI_WEBHOOK_SECRET to the secret revealed in the dashboard, and run:

node webhook-receiver.mjs

The receiver listens at http://127.0.0.1:3000/hcti. Put it behind your public HTTPS endpoint or a development HTTPS tunnel, and preserve the raw request body. PORT changes the local port. WEBHOOK_DB changes the database path, which defaults to ./webhooks.sqlite.

import { createHmac, timingSafeEqual } from 'node:crypto';
import { createServer } from 'node:http';
import { DatabaseSync } from 'node:sqlite';

const secret = process.env.HCTI_WEBHOOK_SECRET;
if (!secret?.startsWith('whsec_')) {
  throw new Error('Set HCTI_WEBHOOK_SECRET to your dashboard signing secret');
}

// Keep this file and its SQLite sidecar files on persistent local storage.
const db = new DatabaseSync(process.env.WEBHOOK_DB || './webhooks.sqlite');
db.exec(`
  PRAGMA journal_mode = WAL;
  PRAGMA synchronous = FULL;
  PRAGMA busy_timeout = 1000;
  CREATE TABLE IF NOT EXISTS webhook_inbox (
    event_id TEXT PRIMARY KEY,
    type TEXT NOT NULL,
    payload TEXT NOT NULL,
    received_at TEXT NOT NULL,
    processed_at TEXT
  ) STRICT;
`);
const accept = db.prepare(`
  INSERT INTO webhook_inbox (event_id, type, payload, received_at, processed_at)
  VALUES (?, ?, ?, ?, ?)
  ON CONFLICT (event_id) DO NOTHING
`);

function verifyWebhook(rawBody, headers) {
  const id = headers.get('webhook-id');
  const timestamp = headers.get('webhook-timestamp');
  const signatures = headers.get('webhook-signature');
  if (!id || !timestamp || !signatures || !/^\d+$/.test(timestamp)) {
    throw new Error('Missing or invalid webhook headers');
  }
  const age = Math.abs(Date.now() / 1000 - Number(timestamp));
  if (!Number.isFinite(age) || age > 300) {
    throw new Error('Webhook timestamp outside tolerance');
  }
  const key = Buffer.from(secret.slice(6), 'base64');
  const expected = createHmac('sha256', key)
    .update(`${id}.${timestamp}.`)
    .update(rawBody)
    .digest();
  const valid = signatures.split(/\s+/).some(signature => {
    const [version, encoded] = signature.split(',');
    if (version !== 'v1' || !encoded) return false;
    const received = Buffer.from(encoded, 'base64');
    return received.length === expected.length &&
      timingSafeEqual(received, expected);
  });
  if (!valid) throw new Error('Invalid webhook signature');
}

const server = createServer(async (request, response) => {
  if (request.method !== 'POST' || request.url?.split('?')[0] !== '/hcti') {
    response.writeHead(404).end();
    return;
  }

  let rawBody;
  try {
    const chunks = [];
    let bytes = 0;
    for await (const chunk of request) {
      bytes += chunk.length;
      if (bytes > 8 * 1024 * 1024) {
        response.writeHead(413).end();
        return;
      }
      chunks.push(chunk);
    }
    rawBody = Buffer.concat(chunks);
    verifyWebhook(rawBody, new Headers(request.headers));
  } catch {
    response.writeHead(400).end('Invalid webhook request');
    return;
  }

  let event;
  try {
    event = JSON.parse(rawBody.toString('utf8'));
    if (typeof event?.event_id !== 'string' || !event.event_id ||
        typeof event.type !== 'string' || !event.type) {
      throw new Error('Invalid envelope');
    }
  } catch {
    response.writeHead(400).end('Invalid event envelope');
    return;
  }

  try {
    const now = new Date().toISOString();
    // This single committed insert both deduplicates and queues business events.
    // Test events are recorded as processed and never start business work.
    accept.run(event.event_id, event.type, rawBody.toString('utf8'), now,
      event.type === 'webhook_test' ? now : null);
    response.writeHead(204).end();
  } catch (error) {
    console.error('Could not persist webhook:', error.code);
    response.writeHead(503).end('Try again later');
  }
});

server.listen(Number(process.env.PORT || 3000), '127.0.0.1', () => {
  console.log(`Webhook receiver: http://127.0.0.1:${server.address().port}/hcti`);
});

The inbox is also the queue. A separate worker can select rows where processed_at IS NULL, perform the action using event_id as its idempotency key, and set processed_at only after success. Handle unfamiliar event types or schema versions deliberately rather than assuming they have an existing payload shape. A worker crash can repeat an action before marking the row, so downstream idempotency still matters.

This example deduplicates by event_id for one organization’s workflow, including deliveries from multiple webhook endpoints. Preserve the database and its sidecar files on persistent local storage across restarts. For receivers running across multiple machines, use a shared durable database or queue with equivalent atomic deduplication. Keep deduplication records for as long as events can be retried or recovered in your workflow.

Image creation usually returns an image ID and URL before rendering. Rendering starts when the image URL is requested, or when your application calls the authenticated store URL for custom-storage-only output. Registering a webhook does not start a render.

image_stored reports a saved base file, with one event per location: hcti_storage or customer_storage. Saving to both locations produces two events. Cached responses, resized or reformatted copies of an already stored image, and debugger captures do not produce another base-storage event.

Do not assume exactly one event per image ID. Separate concurrent renders can produce distinct storage events, each with its own event_id. These are different from retries of one event. If your business action should happen once per image and storage location, enforce that rule using a key such as (image_id, location) in addition to delivery deduplication. For bucket workflows, also inspect location_details to identify the destination and object.

Open Webhook History, or choose View delivery history on a webhook to filter by that destination. Open an event to see its envelope and payload, destination statuses, attempt times, HTTP results, and the configuration version used for each attempt. Response bodies and response headers are not retained.

History is retained for 365 days. Very large payloads may be unavailable in older archived history. A missing payload does not mean an event was never delivered. Secret delivery parameter values are never shown.

GET /v1/webhooks/events/{event_id} and MCP get_webhook_event retrieve one known event. Reading its payload also requires read access to its resource. Without that access, data is null and payload_withheld is true. The dashboard provides the browsable history list.

Pending and retry attempts use the webhook’s current delivery settings when dispatched. Disabling or deleting it, or removing its event subscription, stops queued deliveries. A request already in flight may still reach your endpoint. Creating, enabling, or changing an enabled webhook’s URL, parameters, or signing setting queues a webhook_test. Renaming it or changing only its subscriptions does not queue a test.

Expand a resource group, then an event for its definition and example. The JSON examples in this section show data only. Every delivery wraps this data in the event envelope. Examples use illustrative IDs and values. Nullable fields and additional rendering/provider settings may also be present.

Resource lifecycle events follow the shared entity structure, including its rules for secret fields and truncated text.

{
  "image_id": "01a135fb-21fa-7027-9b82-70acc0e1fd16",
  "width": 1200,
  "height": 630,
  "file_size_bytes": 48210,
  "location": "customer_storage",
  "location_details": {
    "storage_destination_id": "example_storage_id",
    "bucket": "social-images",
    "path": "posts/01a135fb-21fa-7027-9b82-70acc0e1fd16.png"
  }
}

{
  "image_ids": [
    "01a135fb-21fa-7027-9b82-70acc0e1fd16",
    "01a13603-b907-7f63-a402-56d9c89865bd"
  ]
}

{
  "entity": { "type": "template", "id": "example_template_id" },
  "properties": {
    "template_type": "html_css",
    "version": 12345,
    "name": "Social card",
    "description": null,
    "html": { "value": "<h1>Hi</h1>", "truncated": false, "length": 11, "ender": null },
    "css": null,
    "google_fonts": null,
    "viewport_width": 1200,
    "viewport_height": 630
  }
}

{
  "entity": { "type": "template", "id": "example_template_id" },
  "changes": {
    "name": { "kind": "value", "previous_value": "Social card", "new_value": "Product card" },
    "version": { "kind": "value", "previous_value": 12345, "new_value": 12346 }
  }
}

{ "entity": { "type": "template", "id": "example_template_id" } }

{
  "entity": { "type": "proxy", "id": "example_proxy_id" },
  "properties": {
    "name": "Rendering proxy",
    "url": "https://proxy.example.com",
    "port": 8443,
    "bypass_hosts": [],
    "username": "render-user",
    "password_assigned": true,
    "enabled": true
  }
}

{
  "entity": { "type": "proxy", "id": "example_proxy_id" },
  "changes": {
    "enabled": { "kind": "value", "previous_value": true, "new_value": false },
    "password": { "kind": "secret", "previous_assigned": true, "new_assigned": true }
  }
}

{ "entity": { "type": "proxy", "id": "example_proxy_id" } }

{
  "entity": { "type": "storage_destination", "id": "example_storage_id" },
  "properties": {
    "name": "Social images",
    "enabled": true,
    "hcti_storage_disabled": false,
    "connection_info": {
      "provider": "cloudflare_r2",
      "cloudflare_account_id": "0123456789abcdef0123456789abcdef",
      "access_key_id": "your-access-key-id",
      "bucket": "social-images",
      "key_prefix": "posts/"
    },
    "secret_access_key_assigned": true
  }
}

{
  "entity": { "type": "storage_destination", "id": "example_storage_id" },
  "changes": {
    "connection_info.bucket": { "kind": "value", "previous_value": "old-images", "new_value": "social-images" },
    "secret_access_key": { "kind": "secret", "previous_assigned": true, "new_assigned": true }
  }
}

{ "entity": { "type": "storage_destination", "id": "example_storage_id" } }

{
  "entity": { "type": "og_config", "id": "example_og_config_id" },
  "properties": {
    "config_type": "html_css",
    "name": "Website cards",
    "description": null,
    "base_url": "https://example.com",
    "optimization_mode": "no_optimization",
    "enabled": true,
    "refresh_interval_s": 86400,
    "default_options": { "viewport_width": 1200, "viewport_height": 630 },
    "css": null,
    "extract_values": false
  }
}

{
  "entity": { "type": "og_config", "id": "example_og_config_id" },
  "changes": {
    "refresh_interval_s": { "kind": "value", "previous_value": 86400, "new_value": 3600 }
  }
}

{ "entity": { "type": "og_config", "id": "example_og_config_id" } }

{
  "entity": { "type": "api_key", "id": "example_key_id" },
  "properties": {
    "api_id": "your-api-id",
    "name": "Publishing service",
    "description": null,
    "enabled": true,
    "all_future_permissions": false,
    "permissions": ["images:create", "images:read"]
  }
}

{
  "entity": { "type": "api_key", "id": "example_key_id" },
  "changes": {
    "permissions": {
      "kind": "value",
      "previous_value": ["images:create"],
      "new_value": ["images:create", "images:read"]
    }
  }
}

{ "entity": { "type": "api_key", "id": "example_key_id" } }

{
  "previous_plan": "Basic",
  "previous_credits_allowed": 50000,
  "new_plan": "Pro",
  "new_credits_allowed": 100000,
  "changed_at": "2026-10-29T14:00:00Z"
}

{
  "previous_period_credits_used": 42310,
  "period_start": "2026-10-29T00:00:00Z",
  "period_end": "2026-11-29T00:00:00Z",
  "plan": "Basic",
  "credits_allowed": 50000
}

{
  "threshold_percent": 80,
  "credits_used": 40002,
  "credits_allowed": 50000,
  "period_start": "2026-10-29T00:00:00Z"
}

{
  "webhook_id": "example_webhook_id",
  "config_version": 1
}