Configure webhooks

Webhooks send HTTP POST requests to your server when events happen in your Topicary project, for example, when a topic is published or a publication target goes live. Use webhooks to trigger CI/CD pipelines, sync external systems, or build custom notifications.

Before you begin #

Create a webhook #

1. Go to Settings in the sidebar.

2. Open the Webhooks tab.

3. Click Add Webhook.

4. Enter the endpoint URL, the HTTPS URL where Topicary will send events.

5. Select one or more event types from the list below.

6. Click Create.

Topicary generates a signing secret for the webhook automatically. Copy it, you will need it to verify incoming requests.

Event types #

Payload format #

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

{
  "event": "topic.status_changed",
  "data": {
    "id": "topic_xyz789",
    "title": "Getting started",
    "status": "published"
  },
  "timestamp": "2026-06-09T14:30:00Z"
}

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 is marked as failed. Check the delivery log to diagnose failures.

Delivery log #

Each webhook has a delivery log showing recent requests:

• Status: success (2xx), retrying, or failed

• Timestamp: when the delivery was attempted

• Response code: the HTTP status code your endpoint returned

• Response time: how long your endpoint took to respond

Go to Settings > Webhooks, click a webhook, and open the Deliveries tab to view the log.

Rotate the signing secret #

If a signing secret is compromised:

1. Go to Settings > Webhooks and select the webhook.

2. Click Rotate Secret.

3. Update your endpoint to use the new secret.

See also #

• REST API overview: programmatic access to Topicary data

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

• Sync with GitHub: GitHub webhook handler for bidirectional sync

• Plans and limits: webhooks require a Business plan