Webhooks

Receive real-time event notifications from BasaltCRM. Webhooks push data to your endpoints when key events occur — payments, voice calls, email delivery, and form submissions.

How Webhooks Work

Event Fires

An action occurs in BasaltCRM (payment, call, email).

Payload Built

A JSON payload is constructed with event type and data.

Signature Added

HMAC-SHA256 signature is computed and attached as a header.

POST Delivered

HTTP POST sent to your endpoint. Expects a 2xx response.

Signature Verification

Always verify webhook signatures in production to prevent forged events. BasaltCRM signs webhook payloads using HMAC-SHA256 with your configured secret.

import crypto from "crypto"; function verifyWebhookSignature( rawBody: string, signature: string | null, secret: string ): boolean { if (!signature) return false; const expected = crypto .createHmac("sha256", secret) .update(rawBody) .digest("hex"); return crypto.timingSafeEqual( Buffer.from(signature), Buffer.from(expected) ); } // Usage in your endpoint: const isValid = verifyWebhookSignature( rawBody, req.headers["x-surge-signature"], process.env.SURGE_WEBHOOK_SECRET ); if (!isValid) { return res.status(401).json({ error: "Invalid signature" }); }

Webhook Endpoints

SURGE Payment Webhook

POST /api/webhooks/surge

HMAC-SHA256 via X-Surge-Signature headerEnv: SURGE_WEBHOOK_SECRET

Events

payment.confirmed

Payment has been confirmed on-chain. Invoice is marked PAID, linked Opportunity is moved to Close Won.

payment.succeeded

Alias for payment.confirmed. Triggers the same pipeline update.

Example Payload

{ "type": "payment.confirmed", "data": { "id": "pay_abc123", "external_id": "inv_64f...", // Your Invoice ID "amount": "499.00", "currency": "USDC", "network": "base", "tx_hash": "0x..." } }

Automated Side Effects

Updates Invoice → PAID status
Fulfills LeadGen Credits (if applicable)
Syncs Mercury bank invoice
Moves linked Opportunity → Closed Won

BasaltECHO Voice Events

POST /api/voice/engage/webhook

HMAC-SHA256 via x-basaltecho-signature header (optional)Env: BASALTECHO_WEBHOOK_SECRET

Events

tool_call (schedule_meeting)

AI agent requested to schedule a meeting. Creates a calendar event and advances lead pipeline to Engage_Human.

call_connected

Outbound or inbound call has been connected. Updates lead call_status to CONNECTED.

call_ended

Call has ended. Logs duration, updates lead status, and queues follow-up intent.

Example Payload

{ "type": "tool_call", "name": "schedule_meeting", "leadId": "lead_64f...", "args": { "datetime": "2026-03-01T15:00:00Z", "timezone": "America/Denver" }, "eventId": "evt_unique_123", "ts": 1740862800000 }

Automated Side Effects

Creates meeting via /api/outreach/meeting/[leadId]
Advances lead pipeline stage
Logs activity with idempotency (duplicate eventId detection)

Resend Email Events

POST /api/resend/webhook

Resend signature header (recommended in production)Env: RESEND_WEBHOOK_SECRET

Events

email.bounced

Email bounced — updates outreach status to prevent further sends.

email.delivered

Email successfully delivered to inbox.

email.opened

Recipient opened the email (tracking pixel).

email.complained

Recipient marked email as spam.

Example Payload

{ "type": "email.delivered", "data": { "email_id": "msg_abc", "to": "[email protected]", "subject": "Re: Partnership Opportunity", "created_at": "2026-02-27T20:00:00Z" } }

Automated Side Effects

Updates outreach record status (SENT → OPENED)
Enriches lead activity timeline

Azure AI / OpenAI Realtime

POST /api/azure/webhook

HMAC-SHA256 via Webhook-Signature header (Standard Webhooks)Env: OPENAI_WEBHOOK_SECRET / AZURE_OPENAI_WEBHOOK_SECRET

Events

response.completed

AI model response generation completed.

response.failed

Model response generation failed.

realtime.call.incoming

Incoming call detected on Azure Communication Services.

Example Payload

{ "type": "response.completed", "id": "evt_abc", "data": { "session_id": "sess_xyz", "model": "gpt-4o-realtime", "duration_ms": 3200 } }

Automated Side Effects

Logs event for analytics
Routes incoming calls to appropriate handlers

Form Submission Webhook

Configured per-form via webhook_url

Outbound webhook — your endpoint receives POST requestsEnv: N/A (configured in Form Builder UI)

Events

form.submitted

A new form submission was received. Payload includes extracted lead data and UTM parameters.

Example Payload

{ "form_id": "64f...", "form_name": "Contact Us", "submission_id": "64f...", "submitted_at": "2026-02-27T20:30:00Z", "data": { "firstName": "John", "lastName": "Doe", "email": "[email protected]", "company": "Acme Corp", "message": "Interested in the PRO plan" }, "utm": { "source": "google", "medium": "cpc", "campaign": "spring_2026" } }

Automated Side Effects

Creates lead record (if field mapping configured)
Sends auto-respond email (if enabled)
Notifies configured email addresses

Best Practices

• Respond quickly. Return a 200 status within 5 seconds. Process heavy logic asynchronously.
• Handle duplicates. Use the eventId field for idempotent processing.
• Verify signatures. Always validate HMAC signatures in production to prevent replay attacks.
• Use HTTPS. Webhook endpoints must use TLS/SSL. HTTP endpoints are rejected.

Signature Verification

Always verify webhook signatures in production to prevent forged events. BasaltCRM signs webhook payloads using HMAC-SHA256 with your configured secret.

Webhook Endpoints

SURGE Payment Webhook

POST /api/webhooks/surge

HMAC-SHA256 via X-Surge-Signature headerEnv: SURGE_WEBHOOK_SECRET

Events

payment.confirmed

Payment has been confirmed on-chain. Invoice is marked PAID, linked Opportunity is moved to Close Won.

payment.succeeded

Alias for payment.confirmed. Triggers the same pipeline update.

Example Payload

{ "type": "payment.confirmed", "data": { "id": "pay_abc123", "external_id": "inv_64f...", // Your Invoice ID "amount": "499.00", "currency": "USDC", "network": "base", "tx_hash": "0x..." } }

Automated Side Effects

Updates Invoice → PAID status
Fulfills LeadGen Credits (if applicable)
Syncs Mercury bank invoice
Moves linked Opportunity → Closed Won

BasaltECHO Voice Events

POST /api/voice/engage/webhook

HMAC-SHA256 via x-basaltecho-signature header (optional)Env: BASALTECHO_WEBHOOK_SECRET

Events

tool_call (schedule_meeting)

AI agent requested to schedule a meeting. Creates a calendar event and advances lead pipeline to Engage_Human.

call_connected

Outbound or inbound call has been connected. Updates lead call_status to CONNECTED.

call_ended

Call has ended. Logs duration, updates lead status, and queues follow-up intent.

Example Payload

Automated Side Effects

Creates meeting via /api/outreach/meeting/[leadId]
Advances lead pipeline stage
Logs activity with idempotency (duplicate eventId detection)

Resend Email Events

POST /api/resend/webhook

Resend signature header (recommended in production)Env: RESEND_WEBHOOK_SECRET

Events

email.bounced

Email bounced — updates outreach status to prevent further sends.

email.delivered

Email successfully delivered to inbox.

email.opened

Recipient opened the email (tracking pixel).

email.complained

Recipient marked email as spam.

Example Payload

{ "type": "email.delivered", "data": { "email_id": "msg_abc", "to": "[email protected]", "subject": "Re: Partnership Opportunity", "created_at": "2026-02-27T20:00:00Z" } }

Automated Side Effects

Updates outreach record status (SENT → OPENED)
Enriches lead activity timeline

Azure AI / OpenAI Realtime

POST /api/azure/webhook

HMAC-SHA256 via Webhook-Signature header (Standard Webhooks)Env: OPENAI_WEBHOOK_SECRET / AZURE_OPENAI_WEBHOOK_SECRET

Events

response.completed

AI model response generation completed.

response.failed

Model response generation failed.

realtime.call.incoming

Incoming call detected on Azure Communication Services.

Example Payload

{ "type": "response.completed", "id": "evt_abc", "data": { "session_id": "sess_xyz", "model": "gpt-4o-realtime", "duration_ms": 3200 } }

Automated Side Effects

Logs event for analytics
Routes incoming calls to appropriate handlers

Form Submission Webhook

Configured per-form via webhook_url

Outbound webhook — your endpoint receives POST requestsEnv: N/A (configured in Form Builder UI)

Events

form.submitted

A new form submission was received. Payload includes extracted lead data and UTM parameters.

Example Payload

Automated Side Effects

Creates lead record (if field mapping configured)
Sends auto-respond email (if enabled)
Notifies configured email addresses

Best Practices

• Respond quickly. Return a 200 status within 5 seconds. Process heavy logic asynchronously.
• Handle duplicates. Use the eventId field for idempotent processing.
• Verify signatures. Always validate HMAC signatures in production to prevent replay attacks.
• Use HTTPS. Webhook endpoints must use TLS/SSL. HTTP endpoints are rejected.