Skip to main content
Webhooks allow your application to receive real-time HTTP callbacks when events occur in your DeepSmith workspace. Instead of polling the API for changes, webhooks push data to your server the moment something happens.

​
How it works

1

Register a webhook endpoint

Provide a URL and choose which events you want to subscribe to.
2

DeepSmith sends events

When a subscribed event fires, DeepSmith sends a signed POST request to your URL with the event payload.
3

Your server responds

Return a 2xx status code to acknowledge receipt. Failed deliveries are automatically retried.

​
Key features

Signed payloads

Every delivery is signed with HMAC-SHA256 so you can verify it came from DeepSmith.

Automatic retries

Failed deliveries are retried up to 3 times with exponential backoff (10s, 60s, 5min).

Delivery logs

Full audit trail of every delivery attempt including response status, body, and timing.

Auto-disable

Webhooks are automatically disabled after 10 consecutive failures to protect your endpoint.

​
Supported events

DeepSmith fires webhooks for six event types across your content pipeline:
EventDescription
content.status_updatedAn article’s status changed (e.g., draft to published)
research_batch.status_updatedA research batch completed or failed
agent_task.status_updatedAn AI agent task changed state
topic.status_updatedA topic cluster’s stage changed
iq.status_updatedAn IQ analysis completed or changed stage
sitemap_url.status_updatedSitemap URL processing completed or failed
You can subscribe a single webhook to one or more events. Each webhook can listen to any combination of the six event types.

​
Quick example

Here’s a minimal Node.js server that receives webhook deliveries: 
const express = require("express");
const crypto = require("crypto");

const app = express();
app.use(express.raw({ type: "application/json" }));

app.post("/webhooks/deepsmith", (req, res) => {
  const signature = req.headers["x-webhook-signature"];
  const expected =
    "sha256=" +
    crypto
      .createHmac("sha256", process.env.WEBHOOK_SECRET)
      .update(req.body)
      .digest("hex");

  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    return res.status(401).send("Invalid signature");
  }

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

  res.status(200).json({ received: true });
});

app.listen(3000);

​
Next steps

Create a webhook

Register your first webhook endpoint via the API.

Verify signatures

Learn how to validate webhook signatures in your server.

Event payloads

See the full payload schema for each event type.

Handle deliveries

Understand retry logic, failure handling, and best practices.