Setting up Webhooks

Learn how to receive real-time notifications about events in your Bigmind organization using webhooks.

Webhooks allow you to receive real-time notifications when events happen in your Bigmind organization. Instead of polling the API for changes, Bigmind will send HTTP POST requests to your specified endpoint whenever an event occurs.

What are webhooks?

A webhook is an HTTP callback that delivers event data to your application in real-time. When something happens in Bigmind (like a meeting being transcribed or summarized), we'll send a POST request to your webhook URL with details about the event.

This enables you to:

  • Build real-time integrations — React immediately when events occur
  • Automate workflows — Trigger actions in your systems based on Bigmind events
  • Sync data — Keep your database up-to-date with the latest information
  • Send notifications — Alert your team when important events happen

Creating a webhook destination

Here's how to set up your first webhook:

  1. Navigate to Settings — Click on your avatar in the top right corner and select "Settings"
  2. Go to Webhooks — In the settings sidebar, find and click on "Webhooks"
  3. Create a destination — Click the "Create destination" button
  4. Configure your webhook — You'll be taken to the webhook detail page where you can configure it

Configuring your webhook

On the webhook detail page, you can configure:

  • Name — A descriptive name to help you identify this webhook
  • URL — The endpoint where Bigmind should send event notifications (must be HTTPS)
  • Events — Select which events you want to receive notifications for

Available events

  • Transcription Created — Triggered when a meeting transcription is completed
  • Summary Created — Triggered when a meeting summary is generated

Important: You must select at least one event before you can activate your webhook.

Activating your webhook

Webhooks are created in an inactive state. To start receiving events:

  1. Configure your webhook URL and select at least one event
  2. Click "Save changes" to save your configuration
  3. Click the "Activate webhook" button in the page header

Once activated, Bigmind will begin sending events to your endpoint.

Webhook payload structure

Each webhook delivery includes a JSON payload with event data. Here's an example for a transcription_created event:

{
  "event": "transcription_created",
  "data": {
    "meeting_id": "mtg_abc123",
    "session_id": "ses_xyz789",
    "transcript": "<transcript content in HTML format>",
    "speakers": [
      {
        "name": "John Doe",
        "email": "john@example.com",
        "device_id": "device_123"
      }
    ]
  },
  "webhook_id": "whk_def456",
  "timestamp": "2025-10-10T14:30:00.000Z"
}

Verifying webhook signatures

Every webhook request includes an X-Webhook-Signature header containing an HMAC SHA-256 signature. You should verify this signature to ensure the request actually came from Bigmind.

Your signing secret

When you create a webhook, Bigmind generates a unique signing secret (starting with wsec_). You can find this on your webhook detail page. The first 6 characters are visible, and the rest are masked for security.

To copy your signing secret, click the "Copy" button next to it.

Verifying signatures in your code

Here's how to verify webhook signatures in different languages:

Node.js

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const hmac = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(hmac)
  );
}

// In your webhook handler
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const payload = JSON.stringify(req.body);
  
  if (!verifyWebhook(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process the webhook
  console.log('Event:', req.body.event);
  res.status(200).send('OK');
});

Python

import hmac
import hashlib

def verify_webhook(payload: str, signature: str, secret: str) -> bool:
    expected_signature = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()
    
    return hmac.compare_digest(signature, expected_signature)

# In your Flask app
@app.route('/webhook', methods=['POST'])
def webhook():
    signature = request.headers.get('X-Webhook-Signature')
    payload = request.get_data(as_text=True)
    
    if not verify_webhook(payload, signature, os.environ['WEBHOOK_SECRET']):
        return 'Invalid signature', 401
    
    # Process the webhook
    data = request.json
    print(f"Event: {data['event']}")
    return 'OK', 200

Retry logic and failure handling

Bigmind implements automatic retry logic for failed webhook deliveries:

  • Retry attempts — We'll retry failed deliveries up to 5 times
  • Exponential backoff — Each retry waits longer than the previous one (2^retry seconds)
  • Success criteria — Your endpoint must return a 2xx status code to be considered successful
  • Automatic disabling — After 15 total failures across all deliveries, your webhook will be automatically disabled

Tip: Make sure your webhook endpoint responds quickly (within 5 seconds) and returns a 200 status code. Process the event asynchronously if needed.

Viewing delivery history

To see the delivery history for your webhook:

  1. Go to your webhook detail page
  2. Click "View recent deliveries" in the page header
  3. Review the last 25 delivery attempts

Each delivery shows:

  • Status — Success or failed
  • Event — Which event was delivered
  • Timestamp — When the delivery was attempted
  • Response code — The HTTP status code returned by your endpoint
  • Retry count — How many times we attempted to deliver this event

Best practices

  • Use HTTPS — Always use secure HTTPS endpoints for webhooks
  • Verify signatures — Always verify the webhook signature before processing events
  • Respond quickly — Return a 200 status code immediately, then process the event asynchronously
  • Handle idempotency — Due to retries, you might receive the same event multiple times. Use the event data to detect duplicates
  • Monitor failures — Keep an eye on your webhook's delivery history and fix issues before it gets disabled
  • Test thoroughly — Use tools like ngrok or webhook.site to test your webhook handler during development

Troubleshooting

My webhook was automatically disabled

This happens after 15 failed deliveries. Check your webhook's delivery history to see what went wrong. Common issues:

  • Your endpoint is returning error status codes
  • Your endpoint is timing out (taking longer than 5 seconds)
  • Your endpoint is unreachable or down
  • SSL certificate issues

Fix the issue, then reactivate your webhook by clicking "Activate webhook" in the page header.

I'm not receiving webhooks

Check the following:

  • Is your webhook activated?
  • Have you selected at least one event?
  • Is your URL correct and accessible from the internet?
  • Check the delivery history for error details

Deactivating or deleting webhooks

To temporarily stop receiving events, click "Deactivate webhook" in the page header. You can reactivate it anytime.

To permanently remove a webhook:

  1. Go to the Webhooks list page
  2. Hover over the webhook you want to remove
  3. Click the "Delete" button
  4. Confirm the deletion

Warning: Deleting a webhook is permanent and cannot be undone. You'll need to create a new webhook if you want to receive events again.

Need help?

If you're having trouble with webhooks or need assistance setting up your integration, reach out to our support team or check out our API documentation.

Updated 10/10/2025