Webhooks

Webhooks let your other systems know instantly when something happens. When a lead arrives or an event occurs, Calimatic Connect can notify your application in real time.

When should I use webhooks?

Use webhooks when you want your own application to react to events immediately. For example, you might want to send a welcome email the moment a lead comes in, update a dashboard in real time, or trigger a custom workflow in your own system.

How Webhooks Work

When a provider (like Meta Lead Ads) sends an event to Calimatic Connect, here is what happens:

Receive — The event arrives at Calimatic Connect
Verify — The event's signature is checked to make sure it is authentic
Log — The event is recorded for auditing
Process — Lead data is extracted, cleaned up, and saved
Forward — The event is sent to all your webhook subscriptions
Sync — Lead data is pushed to your connected CRM destinations

Webhook events can also trigger automation Flows for more advanced workflows.

Webhook Verification

Providers like Meta require a verification step before they start sending events. Calimatic Connect handles this automatically — no configuration needed on your part.

For developers: The verification handshake works like this:

# Meta sends a GET request to verify the endpoint

GET /webhook/meta_lead_ads?hub.mode=subscribe&hub.verify_token=...&hub.challenge=...

# Calimatic Connect verifies the token and echoes the challenge

Subscribing to Events

To receive events at your own endpoint, create a webhook subscription. You tell Calimatic Connect where to send events, what types of events you want, and optionally a secret for verifying that the events really came from us.

Create a Subscription

POST /connect/v1/webhooks/:providerType/subscribe

{

"callbackUrl": "https://your-app.com/webhooks/receive",

"eventType": "*",

"callbackSecret": "your-signing-secret"

}

callbackUrl — Your HTTPS endpoint where events will be sent
eventType — Use * for all events, or specify a type like leadgen
callbackSecret — Optional. If set, each forwarded event is signed so you can verify it is authentic

List Subscriptions

GET /connect/v1/webhooks/:providerType/subscriptions

Delete a Subscription

DELETE /connect/v1/webhooks/:providerType/subscribe/:subscriptionId

What You Receive

When events are forwarded to your endpoint, they include these custom headers so you know what kind of event it is and where it came from:

Header	Description
X-Connect-Event	The event type (e.g., `leadgen`)
X-Connect-Provider	The provider type (e.g., `meta_lead_ads`)
X-Connect-Signature	HMAC-SHA256 signature (only if you set a callbackSecret)

For Developers: Verifying Forwarded Webhooks

If you provided a callbackSecret, you can verify the X-Connect-Signature header to confirm the event is authentic:

// Node.js example

const crypto = require('crypto');

const expectedSignature = crypto

.createHmac('sha256', callbackSecret)

.update(rawBody)

.digest('hex');

const isValid = signature === expectedSignature;

Retry Policy

If your endpoint is temporarily unavailable (returns a non-2xx status code), Calimatic Connect retries:

Retry attempts: Up to 3
Wait between retries: Starts at 1 second, up to 15 seconds
All delivery attempts are logged so you can see what happened

Event Statuses

Each incoming webhook event is tracked with a status so you can monitor what is happening:

Status	What it means
`RECEIVED`	Event received and logged
`PROCESSED`	Event processed successfully and lead was extracted
`DUPLICATE`	Lead already exists — no duplicate was created
`FAILED`	Something went wrong during processing