Hootsuite Webhooks & Events

Overview

Hootsuite provides webhook notifications for social stream events when building Hootsuite App Directory integrations. For API-only integrations, you poll for message state changes or implement your own scheduling system with callbacks.

Instructions

Step 1: Poll for Message Status Changes

// Since Hootsuite REST API doesn't push webhooks for message status,
// poll for changes to scheduled messages
async function pollMessageStatus(messageId: string, intervalMs = 30000) {
  const check = async () => {
    const response = await fetch(`https://platform.hootsuite.com/v1/messages/${messageId}`, {
      headers: { 'Authorization': `Bearer ${await getStoredToken()}` },
    });
    const { data } = await response.json();

    if (data.state === 'SENT') {
      console.log(`Message ${messageId} sent at ${data.sentAt}`);
      return data;
    } else if (data.state === 'FAILED' || data.state === 'REJECTED') {
      console.error(`Message ${messageId} failed: ${data.state}`);
      return data;
    }

    console.log(`Message ${messageId}: ${data.state}, checking again...`);
    await new Promise(r => setTimeout(r, intervalMs));
    return check();
  };

  return check();
}

Step 2: Build Custom Scheduling Webhook

// Your own webhook system to track scheduled post status
import express from 'express';

const app = express();
app.use(express.json());

// Cron job checks scheduled posts and fires webhooks
async function checkScheduledPosts() {
  const response = await fetch('https://platform.hootsuite.com/v1/messages?state=SENT&limit=50', {
    headers: { 'Authorization': `Bearer ${await getStoredToken()}` },
  });
  const { data } = await response.json();

  for (const msg of data) {
    // Notify your systems about sent posts
    await fetch(process.env.INTERNAL_WEBHOOK_URL!, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ event: 'post.sent', messageId: msg.id, sentAt: msg.sentAt, text: msg.text }),
    });
  }
}

Step 3: Hootsuite App Directory Webhooks

For apps listed in the Hootsuite App Directory, you receive stream events:

// Webhook handler for Hootsuite App Directory integration
app.post('/webhooks/hootsuite', async (req, res) => {
  const { type, data } = req.body;
  switch (type) {
    case 'message.sent': console.log('Post sent:', data); break;
    case 'message.failed': console.error('Post failed:', data); break;
    case 'stream.message': console.log('New social message:', data); break;
  }
  res.status(200).json({ received: true });
});

Prerequisites

A secret-manager webhook secret, event-origin allowlist, replay-window policy, and opaque event ledger.
A sandbox consumer with a tested disable/cancel control for downstream scheduling or publishing.

Output

Return an event receipt with type, opaque event ID, signature/timestamp result, idempotency outcome, queue state, draft/public assertion, and rollback reference. Exclude payload copy, media, handles, and signatures.

Error Handling

Reject unknown origin, stale/replayed delivery, malformed payload, unknown profile/audience, or non-idempotent retry. Quarantine the event and disable the consumer if integrity or approval is uncertain.

Examples

type=post.approved; event=evt-opaque-9; signature=pass; replay=absent; profile=sandbox-brand; enqueue=once; public_posts=0; rollback=consumer-disabled proves the boundary.

Resources

Next Steps

For performance, see hootsuite-performance-tuning.

hootsuite-webhooks-events