Webhooks

​

What You Can Build

• Slack notifications: Get alerts when new interviews are completed
• Zapier automation: Trigger workflows when transcripts are ready
• Custom analysis: Send transcripts to your own AI models
• CRM integration: Update customer records with interview data
• Real-time dashboards: Push data to analytics platforms

​

Requirements

• A Hallway Pro subscription
• An endpoint URL that can receive POST requests (HTTPS required)
• Basic understanding of webhook security (HMAC verification)

​

Creating a Webhook

​

Webhook Payload

​

Headers

​

Payload Structure

{
  "id": "evt_m5k2j_8x7yAbCdEf",
  "type": "session.processing.completed",
  "created_at": "2026-01-10T15:30:00.000Z",
  "api_version": "2026-01-01",
  "account": {
    "id": "acc_abc123",
    "name": "Acme Research"
  },
  "project": {
    "id": "prj_xyz789",
    "name": "Customer Discovery Q1",
    "status": "active"
  },
  "session": {
    "id": "ses_def456",
    "respondent_name": "Jane Doe",
    "respondent_email": "[email protected]",
    "duration_seconds": 342,
    "completed_at": "2026-01-10T15:25:00.000Z"
  },
  "respondent_attributes": [
    { "category_name": "Department", "option_value": "Engineering" },
    { "category_name": "Role", "option_value": "Manager" }
  ],
  "transcript": {
    "id": "trx_ghi789",
    "full_text": "Interviewer: Hello and welcome...\n\nRespondent: Thank you for having me...",
    "word_count": 1240
  },
  "insights": {
    "count": 8,
    "objectives_covered": 3
  },
  "links": {
    "session": "https://app.hallwayai.com/projects/prj_xyz789/sessions/ses_def456",
    "project": "https://app.hallwayai.com/projects/prj_xyz789"
  }
}

​

Field Descriptions

​

Security

​

Signature Verification

t={timestamp},v1={signature}

• t is the Unix timestamp (seconds) when the webhook was sent
• v1 is the HMAC-SHA256 signature

​

Verification Steps

{timestamp}.{raw_body}

​

Code Examples

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  // Parse signature header
  const parts = signature.split(',');
  const timestamp = parts.find(p => p.startsWith('t='))?.split('=')[1];
  const sig = parts.find(p => p.startsWith('v1='))?.split('=')[1];

  if (!timestamp || !sig) {
    throw new Error('Invalid signature format');
  }

  // Check timestamp (5 minute tolerance)
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - parseInt(timestamp)) > 300) {
    throw new Error('Timestamp too old');
  }

  // Compute expected signature
  const signedPayload = `${timestamp}.${payload}`;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');

  // Constant-time comparison
  if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    throw new Error('Signature mismatch');
  }

  return true;
}

import hmac
import hashlib
import time

def verify_webhook(payload: str, signature: str, secret: str) -> bool:
    # Parse signature header
    parts = dict(p.split('=') for p in signature.split(','))
    timestamp = parts.get('t')
    sig = parts.get('v1')

    if not timestamp or not sig:
        raise ValueError('Invalid signature format')

    # Check timestamp (5 minute tolerance)
    now = int(time.time())
    if abs(now - int(timestamp)) > 300:
        raise ValueError('Timestamp too old')

    # Compute expected signature
    signed_payload = f"{timestamp}.{payload}"
    expected = hmac.new(
        secret.encode(),
        signed_payload.encode(),
        hashlib.sha256
    ).hexdigest()

    # Constant-time comparison
    if not hmac.compare_digest(sig, expected):
        raise ValueError('Signature mismatch')

    return True

require 'openssl'

def verify_webhook(payload, signature, secret)
  # Parse signature header
  parts = signature.split(',').map { |p| p.split('=') }.to_h
  timestamp = parts['t']
  sig = parts['v1']

  raise 'Invalid signature format' unless timestamp && sig

  # Check timestamp (5 minute tolerance)
  now = Time.now.to_i
  raise 'Timestamp too old' if (now - timestamp.to_i).abs > 300

  # Compute expected signature
  signed_payload = "#{timestamp}.#{payload}"
  expected = OpenSSL::HMAC.hexdigest('sha256', secret, signed_payload)

  # Constant-time comparison
  raise 'Signature mismatch' unless secure_compare(sig, expected)

  true
end

def secure_compare(a, b)
  return false unless a.bytesize == b.bytesize
  a.bytes.zip(b.bytes).reduce(0) { |acc, (x, y)| acc | (x ^ y) }.zero?
end

​

Managing Webhooks

​

Testing Webhooks

1. Find your webhook in Settings → Integrations → Webhooks
2. Click the more options menu (three dots)
3. Select Send Test
4. A sample payload will be sent to your endpoint

​

Viewing Delivery History

1. Click the more options menu for your webhook
2. Select Delivery History
3. View recent deliveries with status, response time, and response codes

​

Rotating Secrets

1. Click the more options menu
2. Select Rotate Secret
3. A new secret will be generated
4. Update your endpoint with the new secret immediately

​

Disabling and Deleting

• Disable: Toggle the webhook off to pause deliveries without deleting configuration
• Delete: Remove the webhook permanently via the options menu

​

Retry Logic

​

Success Criteria

• HTTP status code 2xx (200, 201, 202, etc.)
• Response within 30 seconds

​

Auto-Disable

​

Limits

​

Troubleshooting

​

Webhook Not Triggering

• Verify the webhook is enabled (not toggled off)
• Check that the event type matches (e.g., session.processing.completed)
• Ensure the project is included if you set project filters
• Review delivery history for errors

​

Signature Verification Failing

• Ensure you’re using the raw request body (not parsed JSON)
• Check that your secret is correct (no extra whitespace)
• Verify the timestamp is within 5 minutes
• Use constant-time string comparison

​

Endpoint Returning Errors

• Your endpoint must return a 2xx status code
• Response must complete within 30 seconds
• Check your server logs for errors
• Use the Send Test feature to debug

​

Webhook Auto-Disabled

• Check delivery history for the failure pattern
• Fix the underlying issue (endpoint down, auth errors, etc.)
• Re-enable the webhook in Settings
• Consider using the test feature before re-enabling

​

Best Practices

​

FAQ

​

Next Steps

• Claude AI Integration - Connect Claude to analyze your research data
• Understanding Insights - Learn how insights are extracted
• Exporting Data - Other ways to export your data