Agent level Webhooks

​

How Webhooks Work

• Each AI Agent can have its own webhook.
• A single webhook URL can be reused across multiple agents.
• When the selected event occurs, SigmaMind sends a signed JSON payload to your webhook endpoint.
• Your system can then process this payload to perform actions like updating CRM records, triggering workflows, or logging analytics.

​

Supported Webhook Events

• conversation_started – Triggered when a new customer conversation begins.
• conversation_ended – Triggered when a conversation is closed or completed.
• conversation_analysed – Triggered when call analysis is completed.

​

Creating Webhooks

​

1. Using the Dashboard

1. Open the AI Agent you want to connect.
2. Go to Agent Settings → Webhooks.
3. Click on Add Webhook
4. Provide the following details -
   • Webhook Name - Set the name you want to give this webhook.
   • URL - Enter a webhook URL. You’ll find this from your system where you want to receive the events from SigmaMind.
   • Hit Submit to add the Webhook.
     

​

2. Using the API

• The name field is a human-readable identifier for your webhook.
• The url is the endpoint in your system that will receive webhook events.
• The agentId must correspond to an existing Agent in your SigmaMind account.
• The events parameter lists which Agent events will trigger the webhook.

curl --location 'https://api.sigmamind.ai/v1/webhooks' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: key_C6HL3Goru7Q.TlI5kZOKPmDM03Gt39nRBEnxrL*******************' \
--data '{
    "name": "Test Webhook 1",
    "url": "https://your-server.com/webhooks/ai-agent",
    "agentId": "D5D0p7TUs66TTAEAx",
    "events": [
        "conversation_started",
        "conversation_ended"
    ]
}'

​

Security and Verification

​

🔑 Secret Generation

• Each webhook is associated with a unique secret.
• This secret is generated securely using a cryptographically strong random generator.
• We store this secret encrypted at rest.
• You should securely store this secret on your side — it is required to verify incoming webhooks.

​

📦 What We Send

​

Headers

​

Body

• JSON payload (exact content used for signature generation)

​

🔏 How Signature is Generated

signature = HMAC_SHA256(secret, timestamp + "." + payload)

x-webhook-signature: sha256=<hex_encoded_signature>

​

✅ How to Verify Webhook (Client Side)

​

Step 1: Extract values

• signature from header
• timestamp from header
• payload (raw request body)

​

Step 2: Recompute signature

expectedSignature = HMAC_SHA256(secret, timestamp + "." + payload)

​

Step 3: Compare signatures

• Remove prefix sha256= from header signature
• Compare with your computed signature
• Use constant-time comparison to avoid timing attacks

​

Step 4: Validate timestamp (Replay Protection)

• Convert timestamp to current time
• Reject if difference > 5 minutes

if (abs(current_time - timestamp) > 300 seconds) → reject

​

Step 5: Handle idempotency

• Use x-webhook-delivery-id to ensure the same event is not processed multiple times

​

💡 Examples

payload = timestamp + "." + rawBody
computed = HMAC_SHA256(secret, payload)

if (!constantTimeEquals(computed, receivedSignature)) {
    reject request
}

​

Summary

• Webhooks notify your system in real time about Agent events.
• You can create webhooks from the Dashboard or via the API.
• A single webhook URL can be used across multiple AI Agents.
• Supported events include conversation_started and conversation_ended.
• Payloads are signed with a secret key for secure delivery.