Extending Socialhose Beyond the Dashboard
While Socialhose provides a comprehensive interface for viewing and analyzing mentions, many organizations need to integrate social listening data into their existing systems. Perhaps you have a custom dashboard that aggregates data from multiple sources. Maybe you want to automatically create support tickets when negative mentions appear. Or you might need to store mention data in your own database for custom analysis and long-term archival.
Webhooks make all of this possible. Instead of constantly polling for new data, your systems receive instant notifications whenever relevant events occur. This real-time data delivery enables sophisticated integrations that would be impractical or impossible with traditional approaches. This guide explains how webhooks work, how to set them up securely, and how to build reliable integrations that enhance your social listening capabilities.
Understanding How Webhooks Work
A webhook is essentially a user-defined HTTP callback. When something happens in Socialhose - a new mention is collected, a mention is enriched, a campaign is paused - the system makes an HTTP POST request to a URL you specify, delivering a payload of data about the event. Your server receives this request, processes the data however you need, and responds to acknowledge receipt.
This model inverts the traditional request-response pattern. Instead of your application asking Socialhose "do you have any new data?" repeatedly, Socialhose tells your application "here's new data" the moment it becomes available. This push-based architecture reduces latency (data arrives in seconds rather than waiting for your next poll), reduces load (no wasted requests when nothing has changed), and simplifies your code (no need to manage polling intervals and state tracking).
The tradeoff is that your application must be able to receive incoming HTTP requests, which means running a server that's accessible from the internet. This is straightforward for organizations with existing web infrastructure, but may require additional setup if you're not already running internet-facing services.
Supported Events
Socialhose webhooks can notify you about several types of events. The most commonly used is mention.enriched, which fires whenever a new mention is AI enriched that matches your campaign's keywords. This event includes comprehensive data about the mention: the content text, author information, platform, sentiment classification, engagement metrics, and a direct link to the original post.
The campaign.paused event fires when a the campaign is paused. This can be useful for when an account quota has been exceeded, triggering a pause. Or if someone accidentally pauses a campaign!
When configuring a webhook, you select which events trigger delivery. You might configure one endpoint to receive all mention.enriched events for feeding a data warehouse, and a separate endpoint to receive only campaign.paused events for audit logging. This separation lets you route different data to different systems based on your integration needs.
Setting Up Your First Webhook
Webhook configuration happens at the campaign level. Navigate to your campaign and click on the Webhooks tab. Click "Add Endpoint" to create a new webhook configuration.
Start by giving your webhook a descriptive name that indicates its purpose: "Slack Notifications" or "Data Warehouse Feed" rather than "Webhook 1." This helps when you're managing multiple webhooks and need to quickly understand what each one does.
The URL field specifies where Socialhose will send event data. This must be an HTTPS endpoint - HTTP is not supported for security reasons. The URL should be a stable address that won't change, as updating webhook URLs requires reconfiguration. Many organizations use dedicated subdomains or paths for webhook receivers: something like https://webhooks.yourcompany.com/socialhose.
Select which events this webhook should receive. For most data integration use cases, mention.enriched is the primary event of interest. Select additional events if your integration needs to respond to them.
Finally, set the webhook status to Active. You can pause webhooks temporarily by toggling to Inactive - useful during maintenance or troubleshooting - without deleting the configuration.
Understanding the Payload Structure
When an event occurs, Socialhose sends a JSON payload to your endpoint. Understanding this structure is essential for building your integration.
The payload includes a top-level event field indicating which event type triggered this delivery, and a timestamp field showing when the event occurred. The data object contains the actual event payload, which varies by event type.
For mention.enriched events, the data object includes the mention ID (useful for deduplication), campaign ID (identifying which campaign captured this mention), the full content text, author information (name, handle, follower count, verification status), platform source, sentiment classification, engagement metrics at the time of collection, and a direct URL to the original post. This comprehensive payload gives your integration everything it needs to process the mention without requiring additional data lookups.
Payloads are delivered as JSON with UTF-8 encoding. Content-Type headers are set appropriately, and the request body contains only the JSON payload. Your receiving endpoint should parse this as standard JSON.
Below is an example of a Payload:
{
"event": "mention.enriched",
"timestamp": "2025-12-24T21:17:55.972745+00:00",
"data": {
"id": "e601c88d-8b72-4738-b2b8-33c3c347ba6e",
"platform": "reddit",
"platform_id": null,
"content": "[QCrit] Adult Science Fiction, The Deadliest Grocery Run, 99k First Attempt\nCollege student Annie Pearson faults herself for her family’s death. Burdened by false guilt and hazy-minded, Annie befriends a dangerous enemy: Liza, an alien studying and harvesting human brains. \n\n\n\nWhen Liza’s research reaches a turning point, she abducts Annie to her spaceship. There, multiple holographic grocery stores brim with other human test subjects sentenced to fight each other to the death. The aliens mistakenly believe that humanity’s natural habitat is the store and that war is our primary pastime. With their deadly coupon wargames, the aliens think they’ve created the perfect habitat.\n\n\n\nUpon winning each Kroger fever dream gauntlet, customers graduate to a different fake store and a harder level of shopping. Those who win each level are told they’ll earn a ticket home.\n\n\n\nBut rare is the advertisement whose promises come true. Someone leads these wargames. Once Annie makes a name for herself as a leading contender in the Run, she graduates not to the next level but instead to the Run’s headquarters, where the smartest and most deadly Grocery Run fighters lead the show. In headquarters, death offers no discounts, and she must face the fact that her continued survival will cost her humanity come checkout.\n\n\n\nBetween the flame-throwers brandished by fellow captives and the infinite (yet sometimes poisonous) free samples, Annie engages in a shopping spree worse than a Y2K Black Friday. It’s a good thing she already has a kill count, because only the best customer can win the most cutthroat grocery run in the galaxy.\n\n\n\nGROCERY RUN is my answer to Cato yelling Clove’s name during the feast scene in *The Hunger Games.* I grew up near Denver, where the Capital was in the story, and living where the villain does in her story, I feel that Collins’s tale revolves around more than the downtrodden. Should there be empathy for evil? What would the Games be like from the Career’s perspective? From the Gamemaker’s? My story is a retelling of *Dante’s Inferno* with aliens playing the part of demons and a main character whose Beatrice is the Devil. Think *Ender's Game* mashed with *The Hunger Games,* taking place at Trader Joe's. THE GROCERY RUN is a 99,000 word Adult Science Fiction. It is similar to how *Sunrise on the Reaping* by Suzanne Collins is dark and self-deprecating, yet contains gossamer threads of sardonic humor to stitch the gore together.\n\n\n\nI earned an English B.A. and I am also a first-year law student at \\*\\*\\* with a penchant for baking, mountain trail-running 5K every day, and microscopically small dogs (who also like to run).\n\n\n\nFirst 300 words:\n\n\n\n“Your brain smells delicious, Annie. Let’s keep going.”\n\nI nodded and threw the axe, landing it solidly in the center of the study room inside the library.\n\n“Excellent,” clipped Liza, an alien researcher. Her eyes glowed a bright green as she scooped a handful of teeth from a bowl on her desk and ate them. The small kernels screamed while she chewed. “A few more reps, then my assistant will transport down to administer the last test.” Finally.\n\nMy light curls rustled against my cheeks. A soft breeze lazily stretched through the open window of the library. Reserved for the next hour, sufficient time for an alien cleanup crew to erase remnants of our session before any other university students interrupted. Late summer called to me with smells like hot dust, growing things, and barbecue. Shouts and laughter pealed from a party outside. It didn’t matter. Loud, though.\n\nLiza flipped a notecard, eyeing me as I turned to face her again. Logic games.\n\n“If God is love,” I stated, reading the card. I tried to breathe through my mouth because the wafts of tangy pork were otherwise distracting. “And love is blind, then what is God?” I thought about the question as I strode to retrieve my weapon. “God is blind.”\n\nLiza nodded. “As a bat.” The games weren’t about sense—just cold knowledge, and I answered based on the frigidity provided and nothing else. “A few more,” she said, her voice slicing through my thoughts like a tortilla chip slipping through nacho cheese. She flipped another card as I yanked the axe from the target and retreated.\n\nMy throat tightened. “And then your assistant will—”\n\n“Will test you and the outcome will permit transport to the starship,” she cut in. “Or preclude.” She waved the card, narrowing her eyes.",
"title": null,
"summary": "The content describes a science fiction narrative involving Annie Pearson, who navigates a deadly grocery run orchestrated by aliens, reflecting on themes of guilt and survival.",
"content_type": "text",
"url": "https://socialho.se/2coXId",
"domain": "www.reddit.com",
"content_links": [],
"sentiment": "neutral",
"sentiment_score": 0.1,
"classification": "news",
"status": "new",
"priority": "medium",
"is_spam": false,
"engagement": {
"likes": 2,
"shares": 0,
"comments": 2,
"views": 0,
"plays": 0,
"favorites": 0,
"upvotes": 0,
"reach": null,
"engagement_count": 4,
"engagement_score": null,
"total_engagement": 4
},
"author": {
"id": "efc7a0b3-bd7e-4967-ad6d-12f9dbbb3a89",
"platform_user_id": "R-Elmer123465",
"platform": "reddit",
"handle": "R-Elmer123465",
"name": null,
"bio": null,
"url": null,
"profile_image_url": null,
"location": null,
"age": null,
"gender": null,
"verified": false,
"is_business_account": false,
"is_paid": false,
"profile_type": "",
"followers_count": 0,
"following_count": 0,
"posts_count": 0,
"likes_count": 0,
"views_count": 0,
"influence_score": 0,
"profile_create_date": null
},
"media": {
"has_media": false,
"image_urls": [],
"video_urls": [],
"media_urls": []
},
"social_content": {
"hashtags": [],
"user_mentions": [],
"cashtags": []
},
"metadata": {
"language": "en",
"country": null,
"age_restricted": false,
"is_reply": false,
"keywords_matched": [
"Target"
],
"tags": [],
"discovery_input": null,
"found_by_system": null,
"notes": null
},
"timestamps": {
"published_at": "2025-12-24T18:14:36+00:00",
"found_at": null,
"collected_at": "2025-12-24T18:59:21.817802+00:00",
"last_updated": null,
"updated_at": "2025-12-24T18:59:22.072722+00:00"
},
"enrichment": {
"categories": [
"science fiction",
"literature",
"entertainment",
"aliens",
"grocery"
],
"category_confidence": 0.9,
"sentiment": "mixed",
"is_hard_news": false,
"hackishness_score": 0.2,
"reported_violence": true,
"is_recommended": true,
"pros": "Creative storytelling and unique premise.",
"cons": "Violent themes may not appeal to all readers.",
"location_inference": "fictional setting with references to grocery stores",
"inferred_country": null,
"entities": {
"persons": [
"Annie Pearson",
"Liza",
"Suzanne Collins"
],
"organizations": [],
"locations": [
"Denver"
]
},
"sensitive_data": {
"emails": [],
"credit_cards": [],
"cryptocurrencies": [],
"ip_addresses": [],
"ssns": [],
"credentials": []
},
"metadata": {
"brands": [
"Kroger",
"Trader Joe's"
],
"intent": "informational",
"emotions": {
"primary": {
"emotion": "anticipation",
"intensity": 0.7
},
"secondary": {
"emotion": "fear",
"intensity": 0.5
}
},
"products": [],
"ai_confidence": 0.85
},
"source": "ai_analysis",
"created_at": "2025-12-24T18:59:30.339385+00:00"
},
"campaign_id": "CAMPAIGN_ID",
"campaign_name": "Grocery Stores",
"parent_mention_id": null
},
"test": true
}And here are the delivery details:
{
"id": "8f6f7618-2c26-4974-9c1d-76e7926f81e1",
"event_type": "mention.enriched",
"status": "sent",
"http_status": 200,
"attempt_count": 1,
"created_at": "2025-12-24T21:17:55.985478Z",
"last_attempted_at": "2025-12-24T21:17:56.201686Z",
"next_retry_at": null,
"endpoint_url": "https://SOME_URL",
"endpoint_name": "NAME THAT IS DESCRIPTIVE AND TOTALLY NOT JUST MY WEBHOOK"
}Securing Your Webhook Endpoint
Because webhook endpoints receive data from the internet, security is critical. Anyone who discovers your endpoint URL could potentially send fake data to your system. Socialhose addresses this through cryptographic signatures that let you verify the authenticity of each request.
Every webhook request includes an X-Webhook-Signature header containing an HMAC-SHA256 signature computed over the raw request body using your webhook secret. Your webhook secret is generated when you create the endpoint and is visible in the webhook configuration interface.
To verify a request, your endpoint should compute its own HMAC-SHA256 hash of the raw request body (before any JSON parsing) using your stored secret. If your computed signature matches the signature in the header, the request is authentic. If they don't match, reject the request - it either wasn't sent by Socialhose or was tampered with in transit.
Never skip signature verification in production. During development, you might temporarily bypass verification to simplify testing, but any production webhook receiver must validate signatures before processing data. This protects you from both malicious actors and accidental misconfiguration.
Keep your webhook secret confidential. Store it in environment variables or a secrets manager rather than hardcoding it. If you believe your secret has been compromised, regenerate it immediately in the webhook settings - Socialhose will begin signing requests with the new secret, and old signatures will no longer validate.
Building a Reliable Receiver
Webhook receivers should be designed for reliability. Several best practices ensure your integration handles edge cases gracefully.
Respond quickly - return a 200 OK response within 30 seconds. Socialhose waits for your response before considering delivery complete; if your endpoint times out, the delivery will be marked as failed and may be retried. Do any time-consuming processing asynchronously: acknowledge the webhook immediately, queue the payload for processing, and return. This separation between receipt and processing makes your receiver more robust.
Implement idempotent processing. The same webhook may occasionally be delivered more than once - network issues, timeouts, or retry logic can cause duplicate deliveries. Your processing logic should handle this gracefully, typically by checking whether you've already processed a given mention ID before taking action. Storing processed IDs in a database or cache makes deduplication straightforward.
Handle failures gracefully. If your processing logic encounters an error, log it thoroughly for debugging but still return a 200 response if you've received the data. Only return error status codes (4xx, 5xx) when you genuinely cannot accept the data - for example, if signature verification fails. Returning error codes too liberally can trigger excessive retries and potentially cause the webhook to be disabled.
Monitor your endpoint's health. Track success rates, response times, and processing errors. Set up alerting for unusual patterns - a sudden spike in failures might indicate a bug in your processing code or an issue with downstream systems your integration depends on.
Common Integration Patterns
Several integration patterns appear frequently across Socialhose webhook implementations.
Feeding a data warehouse is one of the most common uses. Configure a webhook to receive all mention.enriched events, and your receiver writes each mention to your data warehouse - whether that's a SQL database, a data lake, or a specialized analytics platform. This gives you unlimited historical storage and the ability to run custom queries across your mention data.
Real-time notifications to chat platforms like Slack or Microsoft Teams are another popular pattern. Your receiver formats mention data into a chat message and posts it to a channel via the platform's incoming webhook API. This gives teams instant visibility into mentions without leaving their normal communication tools.
Creating support tickets from negative mentions enables proactive customer service. When your receiver detects a mention with negative sentiment, it automatically creates a ticket in your support system (Zendesk, Freshdesk, ServiceNow, or similar), populating the ticket with mention details and a link to the original post. Support agents see social complaints alongside traditional support channels.
Triggering automated responses is possible for sophisticated integrations. Your receiver might detect certain patterns - mentions containing questions, for example - and trigger automated outreach through your marketing automation platform or CRM. This requires careful implementation to avoid coming across as robotic, but can be effective for scalable engagement.
Monitoring and Troubleshooting
The Webhooks tab in your campaign displays delivery statistics and recent events for each endpoint. Success rate shows the percentage of deliveries that received a successful response from your endpoint. Recent events list individual delivery attempts with their status, allowing you to identify specific failures.
If deliveries are failing, check several common issues. Verify your endpoint URL is correct and accessible from the internet. Confirm your server is responding within the timeout window. Check that your signature verification logic is correct if you're receiving 401 responses. Review your server logs for errors that might be causing 500 responses.
Webhooks that fail repeatedly may be automatically paused to prevent endless retry cycles. If your endpoint is paused, fix the underlying issue, then toggle it back to Active. Deliveries will resume from that point forward - events that occurred while paused are not retroactively delivered.
The test functionality lets you send a sample payload to verify your endpoint is working correctly. Use this during initial setup and after any changes to confirm your integration is receiving and processing data as expected.
Webhooks transform Socialhose from a standalone platform into a connected component of your broader technology ecosystem. By pushing data to your systems in real-time, they enable integrations that make social listening an active, automated part of your business operations. The investment in building reliable webhook receivers pays dividends in operational efficiency and faster response to customer conversations.