Webhooks

Webhooks let you receive signals programmatically, enabling custom integrations with your CRM, notification systems, or internal tools.

Note

Webhooks are available on Pro and Enterprise plans.

Setup

1. Navigate to Notifications

   Go to Alerts → Notifications in your dashboard.

2. Add Webhook Notification

   Click Add Notification and select Webhook as the type.

3. Configure Endpoint

   Enter your webhook URL. This is the endpoint that will receive POST requests.

4. Optional: Add Headers

   Add custom headers if your endpoint requires authentication (e.g., Authorization: Bearer token).

5. Optional: Add Secret

   Add a secret for signature verification. CatchIntent will sign each request so you can verify it’s authentic.

6. Save and Test

   Save your webhook and use the Test button to send a sample payload.

Connecting to Listeners

After creating a webhook notification:

1. Go to Listeners
2. Edit the listener you want to trigger webhooks
3. In the alerts section, select your webhook notification
4. Save the listener

Payload Format

Each webhook POST contains:

{
  "event": "signal.created",
  "timestamp": "2025-01-09T12:00:00Z",
  "data": {
    "id": "sig_abc123",
    "listener_id": "lst_xyz789",
    "listener_name": "Product comparisons",
    "platform": "reddit",
    "community": "r/SaaS",
    "title": "Looking for a Salesforce alternative",
    "content": "Looking for a Salesforce alternative that's better for small teams...",
    "author": "user123",
    "relevance_score": 85,
    "reasoning": "User is actively seeking alternatives to a competitor product",
    "source_url": "https://reddit.com/r/SaaS/comments/...",
    "created_at": "2025-01-09T11:55:00Z"
  }
}

Payload Fields

Field	Description
event	Event type (currently signal.created)
timestamp	When the webhook was sent
data.id	Unique signal identifier
data.listener_id	Which listener triggered this
data.listener_name	Human-readable listener name
data.platform	reddit, hackernews, or bluesky
data.community	Subreddit or platform section
data.title	Post title
data.content	Full post content
data.author	Who posted it
data.relevance_score	0-100 relevance score
data.reasoning	AI explanation of why this matches
data.source_url	Direct link to original post
data.created_at	When the post was created

Signature Verification

Caution

Always verify webhook signatures in production to ensure requests are from CatchIntent.

If you configured a secret, each request includes a signature header:

X-CatchIntent-Signature: sha256=abc123def456...

To verify:

1. Get the raw request body (before parsing)
2. Compute HMAC-SHA256 using your secret
3. Compare with the signature header

const crypto = require('crypto');

function verifySignature(body, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Retry Policy

Failed deliveries (non-2xx response) are retried:

Attempt	Delay
1st retry	1 minute
2nd retry	5 minutes
3rd retry	30 minutes

After 3 failed attempts, the webhook is marked as unhealthy and you’ll be notified.

Use Cases

CRM Integration

Create leads automatically in your CRM:

• Salesforce
• HubSpot
• Pipedrive
• Custom CRM

Custom Notifications

Send to additional channels:

• Microsoft Teams
• Custom mobile apps
• Internal chat systems

Analytics & Tracking

Track signals in your data systems:

• Data warehouses
• Analytics platforms
• Custom dashboards

Automation Workflows

Trigger workflows in automation tools:

• Zapier
• Make (Integromat)
• n8n
• Custom automation

Troubleshooting

Not receiving webhooks?

• Verify your endpoint URL is correct and publicly accessible
• Check that your endpoint returns a 2xx status code
• Ensure the listener is active and connected to the webhook

Getting errors?

• Check your server logs for the incoming request
• Verify your endpoint can parse JSON
• Ensure your endpoint responds within 30 seconds

Webhook marked unhealthy?

• Check your endpoint is working
• Review any recent changes to your server
• Test the webhook again after fixing issues