Webhooks

Webhooks let you receive real-time notifications about transcripts on the Alium platform. Instead of polling the API for new content, you register a URL and Alium sends an HTTP POST request to it when a transcript becomes available.

There are two kinds of webhook, depending on which transcripts you want delivered:

Webhook	Delivers	Set up from
Firehose	Every transcript published and provisioned to your team	Account → Webhooks
Saved-search alert	Only transcripts that match a specific saved search	The saved search itself (in the Alium app)

Both deliver the same transcript payload and follow the same delivery and security rules. Pick the firehose when you want a complete feed of your team's intelligence; pick a saved-search webhook when you only care about transcripts matching particular criteria.

Firehose webhooks

A firehose webhook fires for every transcript published and provisioned to your team, as soon as it goes live. This is the right choice when you want a complete, real-time feed of your team's buyer intelligence.

Firehose webhooks belong to an agent seat

A firehose webhook is owned by an agent seat — a machine identity on your team — not by the person who creates it. Because the webhook belongs to the seat rather than to an individual, it keeps running even if the admin who set it up leaves your company.

To create a firehose webhook (you must be a team admin):

Create an agent seat first, if you don't have one, at Account → Agent Seats. Give it a name like "Production CRM Sync."
Go to Account → Webhooks and choose Add Firehose Webhook.
Pick which agent seat owns the webhook, give it a name, and enter your HTTPS endpoint URL.

Each agent seat can have one firehose webhook. To run more than one firehose endpoint, create additional agent seats. The Webhooks page lists every firehose webhook on your team alongside its owning seat, and lets you send a test delivery or delete it.

You can also use the Zapier integration for a no-code way to subscribe to the firehose and route the data to any of 6,000+ connected apps. (Zapier connections are also authorized against an agent seat, but you set them up entirely from Zapier — no agent-seat steps needed on your end.)

Saved-search webhooks

A saved-search webhook fires only for transcripts that match one of your saved searches, in real time as each match is found. Use this when you only care about transcripts matching specific criteria — an industry, a set of vendors, a buyer profile — rather than the full firehose.

Configure it from the saved search itself: open the search, enable POST each match to a webhook, and enter your endpoint URL. A Test button sends a sample payload so you can confirm your endpoint works before saving.
One webhook per saved search. Create additional saved searches to receive webhooks for different criteria.
Saved-search webhooks also appear in Account → Webhooks with a Saved search badge linking back to the search. They're managed from the saved search, so the Test and Delete actions are disabled on that page.
Unlike firehose webhooks, saved-search webhooks are not tied to an agent seat — they belong to the saved search you created them on.

Payload

Both webhook types send a POST request to your registered URL with the transcript data as a flat JSON object in the request body:

{
  "id": "abc123",
  "title": "Interview with VP Marketing at Acme Corp",
  "publish_date": "2024-03-15",
  "date": "March 2024",
  "management_level": "VP",
  "department": "Marketing",
  "opted_into_intros": true,
  "company": "Acme Corp",
  "company_hq": "California",
  "company_domain_name": "acme.com",
  "company_revenue": "$100M-$500M",
  "company_employee_count": "1,001-5,000",
  "company_industries": ["Retail > Apparel"],
  "in_market_for": ["Email Marketing", "CDP"],
  "strategic_priorities": ["Personalization", "Customer retention"],
  "buyer_perspective": "The VP discussed their focus on...",
  "tech_stack": [
    {
      "product": "Salesforce Marketing Cloud",
      "vendor": "Salesforce",
      "vendor_domain_name": "salesforce.com",
      "rating": 4,
      "use_cases": ["Email campaigns", "Journey builder"]
    }
  ],
  "quick_study": "Q: What are your top priorities?\nA: ...",
  "full_transcript": "Q: Can you tell me about your role?\nA: ...",
  "url": "https://app.alium.io/transcripts/abc123",
  "salesforce_account_ids": ["001XX000003DHPh"]
}

salesforce_account_ids lists the Salesforce account IDs (if any) that match the buyer's company for your team — useful for routing the transcript to the right CRM record.

AI distribution summary

If your integration uses the ai_summaries OAuth scope (available through the Zapier integration), the payload includes an additional top-level field:

{
  "ai_distribution_summary": "This VP of Marketing at Acme Corp is evaluating..."
}

Delivery & security

Webhook payloads are sent as POST requests with a Content-Type: application/json header.
Your endpoint must be served over HTTPS and resolve to a public address — Alium rejects URLs that point at loopback, private, or link-local addresses.
Your endpoint should return a 2xx status code to acknowledge receipt.
Failed deliveries are retried with exponential backoff.

This applies to both firehose and saved-search webhooks.

Verifying signatures

Webhooks you set up directly in Alium (both firehose and saved-search) are signed so you can confirm a request genuinely came from Alium. Each request includes two headers:

Header	Description
`X-Webhook-Timestamp`	Unix timestamp (seconds) of when the request was sent
`X-Webhook-Signature`	Hex-encoded HMAC-SHA256 of `{timestamp}.{raw_request_body}`, keyed with your webhook's signing secret

To verify a request, recompute the HMAC over the timestamp and the raw request body and compare it to X-Webhook-Signature using a constant-time comparison:

import hashlib
import hmac

def is_valid(secret: str, timestamp: str, raw_body: bytes, signature: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        f"{timestamp}.".encode() + raw_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Always compute the HMAC over the raw request body, before any JSON parsing or re-serialization. Webhooks delivered through the Zapier integration are not signed — Zapier authenticates via OAuth instead.

Use cases

Push to CRM — Automatically create records in Salesforce, HubSpot, or other CRMs when new buyer intelligence is published.
Notify your team — Send a Slack or email notification with a summary of new transcripts.
Sync to data warehouse — Stream transcript data to your data warehouse for custom analytics.
Enrich lead scoring — Update lead scores based on buyer intent signals from new transcripts.

Firehose webhooks​

Firehose webhooks belong to an agent seat​

Saved-search webhooks​

Payload​

AI distribution summary​

Delivery & security​

Verifying signatures​

Use cases​