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
```typescript
// 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.