Webhooks Overview

Webhooks allow ChatSpark to push real-time event notifications to your server. Use them to sync data, trigger automations, or update your systems when leads are captured, conversations start, and more.

How to Register

Use the Webhook Management API to register endpoints. Provide a valid HTTPS URL and select the event types you want to receive. You will receive a signing secret. Store it securely to verify payload authenticity.

Delivery Guarantees

ChatSpark attempts delivery for each webhook event. Your endpoint must respond within the required time window.

Retry policy: We retry failed deliveries up to 3 times with exponential backoff.
Response requirement: Return 200 OK within 10 seconds to acknowledge receipt.
Idempotency: Process webhooks idempotently; you may receive duplicate deliveries for the same event.

HMAC-SHA256 Signature Verification

Every webhook request includes an X-ChatSpark-Signature header. Verify it using your webhook secret to ensure the request originated from ChatSpark and was not modified.

javascript

const crypto = require("crypto");

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

Header	Description
`X-ChatSpark-Signature`	HMAC-SHA256 signature of the raw request body, prefixed with `sha256=`

Expected Response

Your endpoint should return 200 OK within 10 seconds. Non-2xx responses or timeouts will trigger retries.

Next Steps

Webhook Events - All event types and payload schemas

Webhook Management API - Register, list, and delete webhook endpoints

Message Feedback

Events