Webhooks

Overview

Webhooks allow your application to receive real-time notifications when events happen in CalyxCRM. When you subscribe to an event, CalyxCRM sends an HTTP POST request to your endpoint with the event data.

Webhooks are powered by Svix, which provides automatic retries, payload signing, and delivery tracking.

Event Types

Managing Webhooks

Via the Dashboard

1. Navigate to Organization Settings → Developers
2. Click the Webhooks tab
3. Click Manage Webhooks to open the webhook management portal

The portal lets you:

• Add endpoints - Configure URLs to receive webhook events
• Choose event types - Subscribe to specific events per endpoint
• View delivery logs - Inspect request/response details for each delivery
• Replay failed deliveries - Retry deliveries that failed
• Test endpoints - Send test events to verify your setup

Via the API

Use the webhook API endpoint to get the portal URL programmatically:

curl -X GET "https://your-domain.com/api/v1/webhooks" \
  -H "Authorization: Bearer caly_your_api_key"

This requires the webhooks:manage scope.

Payload Format

All webhook events are sent as HTTP POST requests with a JSON body:

{
  "organizationId": "org_abc123",
  "recordId": "rec_def456",
  "objectId": "obj_ghi789",
  "data": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com"
  }
}

For activity events, the payload includes activity-specific fields:

{
  "organizationId": "org_abc123",
  "activityId": "act_jkl012",
  "title": "Follow-up Call",
  "linkedRecords": [
    { "objectId": "obj_ghi789", "recordId": "rec_def456" }
  ]
}

Verifying Signatures

Every webhook delivery includes a signature in the headers that you should verify to ensure the request is authentic. Svix provides SDKs to handle verification:

import { Webhook } from "svix";

const wh = new Webhook("whsec_your_signing_secret");

// Inside your webhook handler
const payload = wh.verify(body, headers);

The signing secret is available in the webhook management portal for each endpoint.

Retry Policy

If your endpoint returns a non-2xx status code or times out, Svix will automatically retry the delivery with exponential backoff. Deliveries are retried for up to 3 days.

Best Practices

• Respond quickly - Return a 200 status code as fast as possible. Process the event asynchronously if needed.
• Handle duplicates - In rare cases, the same event may be delivered more than once. Use the event ID for deduplication.
• Verify signatures - Always verify the webhook signature to ensure authenticity.
• Use HTTPS - Always use HTTPS endpoints in production.