Configure webhooks

Webhooks send an HTTP POST to your server when something happens in your Topicary project, for example, when a topic is published. Use them to trigger CI/CD pipelines, sync external systems, or build custom notifications.

Before you begin #

Add a webhook #

1. Go to Settings > Connections and find the Webhooks card.

2. Click Add webhook. While no endpoint is registered, the button sits under the empty state, Add an endpoint to receive project events.

3. Enter the endpoint URL, for example https://example.com/hooks/topicary. It must be a public address: private, loopback, and internal hosts are refused with Webhook URL must be a public HTTPS endpoint.

4. Optionally fill in Description (optional). It is only a label for your own use.

5. Under Events, choose what to subscribe to. All events is selected by default and is exclusive: clicking any named chip, such as Topic Published, clears it. Chip labels are the event names in title case, so Topic Status Changed is topic.status_changed.

6. Click Add webhook again to submit the form. The button stays disabled until the URL field has something in it. Cancel discards the form.

The form refuses a save and says why, inline:

Manage an endpoint #

Each row in the Webhooks card shows the endpoint URL, an Active or Disabled badge, the description, one chip per subscribed event (All events for the wildcard), and the date it was created. Four buttons act on it:

Rotate the signing secret #

1. Go to Settings > Connections > Webhooks and find the endpoint.

2. Click Rotate secret.

3. Read the Rotate signing secret? dialog, which states: "The current secret stops verifying immediately. The new secret is shown once — update your endpoint with it right away."

4. Click Rotate secret to confirm.

The new secret appears in the same one-time banner as a newly created endpoint. Copy it and update your receiver.

Manage webhooks over the REST API #

Everything except secret rotation is also available programmatically. You need an REST API authentication, which only a project Admin can generate.

Send a POST to /api/v1/webhooks with the endpoint URL and the events you want:

curl -X POST https://topicary.com/api/v1/webhooks \
  -H "Authorization: Bearer tk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/topicary",
    "events": ["topic.published", "topic.updated"],
    "description": "Build pipeline"
  }'

The response contains the webhook id and its secret:

{
  "data": {
    "id": "8b1c0f2e-...",
    "url": "https://example.com/hooks/topicary",
    "events": ["topic.published", "topic.updated"],
    "secret": "whsec_9f3c...",
    "is_active": true,
    "description": "Build pipeline",
    "created_at": "2026-09-08T14:30:00Z"
  }
}

Store the secret when the response arrives. Later reads never return it, and the API has no rotation endpoint: rotate from the Webhooks card instead.

Rules the endpoint enforces:

• The URL must be a public http or https address. Private, loopback, and internal hosts are refused with url must be a public HTTPS endpoint.

• events must contain at least one valid event type, or the wildcard "*" to subscribe to every event.

• description is optional and is only a label for your own use.

Event types #

Subscribe with "events": ["*"] to receive all of them.

Payload format #

Every webhook delivery is a POST request with a JSON body:

{
  "event": "topic.status_changed",
  "data": {
    "id": "3f7c2a1e-8b04-4d6f-9a11-2c5e7d0b4f83",
    "status": "published"
  },
  "timestamp": "2026-09-08T14:30:00Z"
}

The data object is deliberately lean: it identifies what changed rather than restating the content. Read the full record over the REST API when you need titles, fields, or body content. The Webhook event reference lists the fields each event carries.

Request headers #

Every webhook request includes the following headers:

Verify signatures #

Every request includes an X-Topicary-Signature header in the format sha256=<hex digest>. The hex digest is an HMAC-SHA256 signature of the raw request body using your webhook's signing secret. Verify this signature to confirm the request came from Topicary:

import crypto from "crypto";

function verifyWebhook(body, signatureHeader, secret) {
  const signature = signatureHeader.replace("sha256=", "");
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

import hmac
import hashlib

def verify_webhook(body: bytes, signature_header: str, secret: str) -> bool:
    signature = signature_header.removeprefix("sha256=")
    expected = hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

Retry behavior #

If your endpoint returns a non-2xx status code or fails to respond within 10 seconds, Topicary retries the delivery. Each webhook is attempted up to 3 times total (the initial delivery plus two retries) with an exponential backoff between attempts:

Retries are processed by a background job, so the actual time between attempts can be slightly longer than the scheduled backoff. After the third failed attempt, the delivery stops being retried.

Redirects are followed, so a receiver that normalizes URLs (trailing slash, www, regional failover) still gets the payload. A paused webhook (is_active: false) receives neither new deliveries nor retries.

Check delivery history #

In Settings > Connections > Webhooks, click Deliveries on an endpoint. The pane lists its 10 most recent attempts, newest first, and reads No deliveries yet. until one is made. Each line shows the event name, the HTTP status your endpoint returned or No response, a Delivered or Failed chip, the attempt count as 1 attempt or N attempts, and the time of the first attempt. Click Deliveries again to collapse the pane.

GET /api/v1/webhooks/{id} returns the same 10 most recent deliveries in recent_deliveries. Each entry records:

See also #

• Webhook event reference: the payload schema for each event type

• REST API overview: base URL, rate limits, and the response envelope

• Connect Zapier: Zaps that register and remove their own webhooks

• Security and data handling: how webhook secrets and HMAC signatures protect your integration

• Plans and limits: webhooks require a Business plan