Documentation

Webhooks

Receive signed HTTP callbacks when accounts connect, posts publish, or tokens expire.

Configuration

Set your webhook URL and secret via PUT /api/v1/webhooks or in the dashboard. unifeed signs each delivery with HMAC-SHA256 using your secret.

PUT /api/v1/webhooks

{
  "url": "https://yourapp.com/api/webhooks/unifeed",
  "webhook_secret": "whsec_..."
}

Verification

unifeed sends X-Unifeed-Signature (hex HMAC of the raw body). Verify before processing:

Node.js

import { createHmac, timingSafeEqual } from "node:crypto";

function verifyUnifeedWebhook(body: string, signature: string, secret: string) {
  const expected = createHmac("sha256", secret).update(body).digest("hex");
  return timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

Event types

account.connected
A social account was linked to a tenant
account.token_expired
A stored token needs reconnect
post.published
A delivery succeeded — includes platformPostId
post.failed
A delivery failed — includes error message
webhook.test
Sent when you call POST /api/v1/webhooks/test

Payload shape

{
  "event": "post.published",
  "tenantId": "ws_abc123",
  "timestamp": "2026-06-01T12:00:00.000Z",
  "data": {
    "unifeedPostId": "...",
    "deliveryId": "...",
    "connectedAccountId": "...",
    "platformPostId": "18077479694646118"
  }
}